Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MOTOR-608 Update outdated API docs #165

Merged
merged 2 commits into from Apr 25, 2022
Merged

MOTOR-608 Update outdated API docs #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bdc673
MOTOR-608 Update outdated API docs
blink1073 Apr 25, 2022
a57420f
address review
blink1073 Apr 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
362 changes: 2 additions & 360 deletions doc/api-asyncio/asyncio_gridfs.rst
View file
Open in desktop
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