Skip to content

Commit

Permalink
MOTOR-608 Update outdated API docs (#165)
Browse files Browse the repository at this point in the history
  • Loading branch information
@blink1073
blink1073 committed Apr 25, 2022
1 parent eb3ed14 commit c564a02
Show file tree
Hide file tree
Showing 8 changed files with 414 additions and 961 deletions.
362 changes: 2 additions & 360 deletions doc/api-asyncio/asyncio_gridfs.rst
View file
Expand Up @@ -8,366 +8,8 @@ Store blobs of data in `GridFS <http://dochub.mongodb.org/core/gridfs>`_.
.. seealso:: :ref:`Differences between PyMongo's and Motor's GridFS APIs
<gridfs-differences>`.


.. class:: AsyncIOMotorGridFSBucket

Create a new instance of :class:`AsyncIOMotorGridFSBucket`.

Raises :exc:`TypeError` if `database` is not an instance of
:class:`AsyncIOMotorDatabase`.

Raises :exc:`~pymongo.errors.ConfigurationError` if `write_concern`
is not acknowledged.

:Parameters:
- `database`: database to use.
- `bucket_name` (optional): The name of the bucket. Defaults to 'fs'.
- `chunk_size_bytes` (optional): The chunk size in bytes. Defaults
to 255KB.
- `write_concern` (optional): The
:class:`~pymongo.write_concern.WriteConcern` to use. If ``None``
(the default) db.write_concern is used.
- `read_preference` (optional): The read preference to use. If
``None`` (the default) db.read_preference is used.

.. mongodoc:: gridfs

.. coroutinemethod:: delete(self, file_id)

Delete a file's metadata and data chunks from a GridFS bucket::

async def delete():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# Get _id of file to delete
file_id = await fs.upload_from_stream("test_file",
b"data I want to store!")
await fs.delete(file_id)

Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists.

:Parameters:
- `file_id`: The _id of the file to be deleted.

.. coroutinemethod:: download_to_stream(self, file_id, destination)

Downloads the contents of the stored file specified by file_id and
writes the contents to `destination`::

async def download():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# Get _id of file to read
file_id = await fs.upload_from_stream("test_file",
b"data I want to store!")
# Get file to write to
file = open('myfile','wb+')
await fs.download_to_stream(file_id, file)
file.seek(0)
contents = file.read()

Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists.

:Parameters:
- `file_id`: The _id of the file to be downloaded.
- `destination`: a file-like object implementing :meth:`write`.

.. coroutinemethod:: download_to_stream_by_name(self, filename, destination, revision=-1)

Write the contents of `filename` (with optional `revision`) to
`destination`.

For example::

async def download_by_name():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# Get file to write to
file = open('myfile','wb')
await fs.download_to_stream_by_name("test_file", file)

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.

Raises :exc:`~ValueError` if `filename` is not a string.

:Parameters:
- `filename`: The name of the file to read from.
- `destination`: A file-like object that implements :meth:`write`.
- `revision` (optional): Which revision (documents with the same
filename and different uploadDate) of the file to retrieve.
Defaults to -1 (the most recent revision).

:Note: Revision numbers are defined as follows:

- 0 = the original stored file
- 1 = the first revision
- 2 = the second revision
- etc...
- -2 = the second most recent revision
- -1 = the most recent revision

.. method:: find(self, *args, **kwargs)

Find and return the files collection documents that match ``filter``.

Returns a cursor that iterates across files matching
arbitrary queries on the files collection. Can be combined
with other modifiers for additional control.

For example::

async def find():
cursor = fs.find({"filename": "lisa.txt"},
no_cursor_timeout=True)

async for grid_data in cursor:
data = grid_data.read()

iterates through all versions of "lisa.txt" stored in GridFS.
Setting no_cursor_timeout may be important to
prevent the cursor from timing out during long multi-file processing
work.

As another example, the call::

most_recent_three = fs.find().sort("uploadDate", -1).limit(3)

returns a cursor to the three most recently uploaded files in GridFS.

Follows a similar interface to :meth:`~AsyncIOMotorCollection.find`
in :class:`AsyncIOMotorCollection`.

:Parameters:
- `filter`: Search query.
- `batch_size` (optional): The number of documents to return per
batch.
- `limit` (optional): The maximum number of documents to return.
- `no_cursor_timeout` (optional): The server normally times out idle
cursors after an inactivity period (10 minutes) to prevent excess
memory use. Set this option to True prevent that.
- `skip` (optional): The number of documents to skip before
returning.
- `sort` (optional): The order by which to sort results. Defaults to
None.

.. coroutinemethod:: open_download_stream(self, file_id)

Opens a stream to read the contents of the stored file specified by file_id::

async def download_stream():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# get _id of file to read.
file_id = await fs.upload_from_stream("test_file",
b"data I want to store!")
grid_out = await fs.open_download_stream(file_id)
contents = await grid_out.read()

Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists.

:Parameters:
- `file_id`: The _id of the file to be downloaded.

Returns a :class:`AsyncIOMotorGridOut`.

.. coroutinemethod:: open_download_stream_by_name(self, filename, revision=-1)

Opens a stream to read the contents of `filename` and optional `revision`::

async def download_by_name():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# get _id of file to read.
file_id = await fs.upload_from_stream("test_file",
b"data I want to store!")
grid_out = await fs.open_download_stream_by_name(file_id)
contents = await grid_out.read()

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.

Raises :exc:`~ValueError` filename is not a string.

:Parameters:
- `filename`: The name of the file to read from.
- `revision` (optional): Which revision (documents with the same
filename and different uploadDate) of the file to retrieve.
Defaults to -1 (the most recent revision).

Returns a :class:`AsyncIOMotorGridOut`.

:Note: Revision numbers are defined as follows:

- 0 = the original stored file
- 1 = the first revision
- 2 = the second revision
- etc...
- -2 = the second most recent revision
- -1 = the most recent revision

.. method:: open_upload_stream(self, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filename, and add any additional information in the metadata
field of the file document or modify the chunk size::

async def upload():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
grid_in = fs.open_upload_stream(
"test_file", metadata={"contentType": "text/plain"})

await grid_in.write(b"data I want to store!")
await grid_in.close() # uploaded on close

Returns an instance of :class:`AsyncIOMotorGridIn`.

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.
Raises :exc:`~ValueError` if `filename` is not a string.

In a Python 3.5 native coroutine, the "async with" statement calls
:meth:`~AsyncIOMotorGridIn.close` automatically::

async def upload():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
async with await fs.open_upload_stream(
"test_file", metadata={"contentType": "text/plain"}) as gridin:
await gridin.write(b'First part\n')
await gridin.write(b'Second part')

# gridin is now closed automatically.

:Parameters:
- `filename`: The name of the file to upload.
- `chunk_size_bytes` (options): The number of bytes per chunk of this
file. Defaults to the chunk_size_bytes in :class:`AsyncIOMotorGridFSBucket`.
- `metadata` (optional): User data for the 'metadata' field of the
files collection document. If not provided the metadata field will
be omitted from the files collection document.

.. method:: open_upload_stream_with_id(self, file_id, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filed_id and filename, and add any additional information in
the metadata field of the file document, or modify the chunk size::

async def upload():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
grid_in = fs.open_upload_stream_with_id(
ObjectId(), "test_file",
metadata={"contentType": "text/plain"})

await grid_in.write(b"data I want to store!")
await grid_in.close() # uploaded on close

Returns an instance of :class:`AsyncIOMotorGridIn`.

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.
Raises :exc:`~ValueError` if `filename` is not a string.

:Parameters:
- `file_id`: The id to use for this file. The id must not have
already been used for another file.
- `filename`: The name of the file to upload.
- `chunk_size_bytes` (options): The number of bytes per chunk of this
file. Defaults to the chunk_size_bytes in :class:`AsyncIOMotorGridFSBucket`.
- `metadata` (optional): User data for the 'metadata' field of the
files collection document. If not provided the metadata field will
be omitted from the files collection document.

.. coroutinemethod:: rename(self, file_id, new_filename)

Renames the stored file with the specified file_id.

For example::


async def rename():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
# get _id of file to read.
file_id = await fs.upload_from_stream("test_file",
b"data I want to store!")

await fs.rename(file_id, "new_test_name")

Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists.

:Parameters:
- `file_id`: The _id of the file to be renamed.
- `new_filename`: The new name of the file.

.. coroutinemethod:: upload_from_stream(self, filename, source, chunk_size_bytes=None, metadata=None)

Uploads a user file to a GridFS bucket.

Reads the contents of the user file from `source` and uploads
it to the file `filename`. Source can be a string or file-like object.
For example::

async def upload_from_stream():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
file_id = await fs.upload_from_stream(
"test_file",
b"data I want to store!",
metadata={"contentType": "text/plain"})

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.
Raises :exc:`~ValueError` if `filename` is not a string.

:Parameters:
- `filename`: The name of the file to upload.
- `source`: The source stream of the content to be uploaded. Must be
a file-like object that implements :meth:`read` or a string.
- `chunk_size_bytes` (options): The number of bytes per chunk of this
file. Defaults to the chunk_size_bytes of :class:`AsyncIOMotorGridFSBucket`.
- `metadata` (optional): User data for the 'metadata' field of the
files collection document. If not provided the metadata field will
be omitted from the files collection document.

Returns the _id of the uploaded file.

.. coroutinemethod:: upload_from_stream_with_id(self, file_id, filename, source, chunk_size_bytes=None, metadata=None)

Uploads a user file to a GridFS bucket with a custom file id.

Reads the contents of the user file from `source` and uploads
it to the file `filename`. Source can be a string or file-like object.
For example::

async def upload_from_stream_with_id():
my_db = AsyncIOMotorClient().test
fs = AsyncIOMotorGridFSBucket(my_db)
file_id = await fs.upload_from_stream_with_id(
ObjectId(),
"test_file",
b"data I want to store!",
metadata={"contentType": "text/plain"})

Raises :exc:`~gridfs.errors.NoFile` if no such version of
that file exists.
Raises :exc:`~ValueError` if `filename` is not a string.

:Parameters:
- `file_id`: The id to use for this file. The id must not have
already been used for another file.
- `filename`: The name of the file to upload.
- `source`: The source stream of the content to be uploaded. Must be
a file-like object that implements :meth:`read` or a string.
- `chunk_size_bytes` (options): The number of bytes per chunk of this
file. Defaults to the chunk_size_bytes of :class:`AsyncIOMotorGridFSBucket`.
- `metadata` (optional): User data for the 'metadata' field of the
files collection document. If not provided the metadata field will
be omitted from the files collection document.
.. autoclass:: AsyncIOMotorGridFSBucket
:members:

.. autoclass:: AsyncIOMotorGridIn
:members:
Expand Down

0 comments on commit c564a02

Please sign in to comment.