mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PYTHON-4047 Convert top level docs files to Markdown (#1432)

Browse Source
This commit is contained in:
Steven Silvester 2023-11-21 14:24:49 -06:00 committed by GitHub
parent ec35f7f76e
commit 51f7fe29f6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 546 additions and 477 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,224 @@
# Contributing to PyMongo
PyMongo has a large
[community](https://pymongo.readthedocs.io/en/stable/contributors.html)
and contributions are always encouraged. Contributions can be as simple
as minor tweaks to the documentation. Please read these guidelines
before sending a pull request.
## Bugfixes and New Features
Before starting to write code, look for existing
[tickets](https://jira.mongodb.org/browse/PYTHON) or [create
one](https://jira.mongodb.org/browse/PYTHON) for your specific issue or
feature request. That way you avoid working on something that might not
be of interest or that has already been addressed.
## Supported Interpreters
PyMongo supports CPython 3.7+ and PyPy3.8+. Language features not
supported by all interpreters can not be used.
## Style Guide
PyMongo follows [PEP8](http://www.python.org/dev/peps/pep-0008/)
including 4 space indents and 79 character line limits.
## General Guidelines
- Avoid backward breaking changes if at all possible.
- Write inline documentation for new classes and methods.
- Write tests and make sure they pass (make sure you have a mongod
running on the default port, then execute `tox -e test` from the cmd
line to run the test suite).
- Add yourself to doc/contributors.rst `:)`
## Authoring a Pull Request
**Our Pull Request Policy is based on this** [Code Review Developer
Guide](https://google.github.io/eng-practices/review)
The expectation for any code author is to provide all the context needed
in the space of a pull request for any engineer to feel equipped to
review the code. Depending on the type of change, do your best to
highlight important new functions or objects you've introduced in the
code; think complex functions or new abstractions. Whilst it may seem
like more work for you to adjust your pull request, the reality is your
likelihood for getting review sooner shoots up.
**Self Review Guidelines to follow**
- If the PR is too large, split it if possible.
- Use 250 LoC (excluding test data and config changes) as a
rule-of-thumb.
- Moving and changing code should be in separate PRs or commits.
- Moving: Taking large code blobs and transplanting
them to another file. There\'s generally no (or very
little) actual code changed other than a cut and
paste. It can even be extended to large deletions.
- Changing: Adding code changes (be that refactors or
functionality additions/subtractions).
- These two, when mixed, can muddy understanding and
sometimes make it harder for reviewers to keep track
of things.
- Prefer explaining with code comments instead of PR comments.
**Provide background**
- The PR description and linked tickets should answer the "what" and
"why" of the change. The code change explains the "how".
**Follow the Template**
- Please do not deviate from the template we make; it is there for a
lot of reasons. If it is a one line fix, we still need to have
context on what and why it is needed.
- If making a versioning change, please let that be known. See examples below:
- `versionadded:: 3.11`
- `versionchanged:: 3.5`
**Pull Request Template Breakdown**
- **Github PR Title**
- The PR Title format should always be
`[JIRA-ID] : Jira Title or Blurb Summary`.
- **JIRA LINK**
- Convenient link to the associated JIRA ticket.
- **Summary**
- Small blurb on why this is needed. The JIRA task should have
the more in-depth description, but this should still, at a
high level, give anyone looking an understanding of why the
PR has been checked in.
- **Changes in this PR**
- The explicit code changes that this PR is introducing. This
should be more specific than just the task name. (Unless the
task name is very clear).
- **Test Plan**
- Everything needs a test description. Describe what you did
to validate your changes actually worked; if you did
nothing, then document you did not test it. Aim to make
these steps reproducible by other engineers, specifically
with your primary reviewer in mind.
- **Screenshots**
- Any images that provide more context to the PR. Usually,
these just coincide with the test plan.
- **Callouts or follow-up items**
- This is a good place for identifying "to-dos" that you've
placed in the code (Must have an accompanying JIRA Ticket).
- Potential bugs that you are unsure how to test in the code.
- Opinions you want to receive about your code.
## Running Linters
PyMongo uses [pre-commit](https://pypi.org/project/pre-commit/) for
managing linting of the codebase. `pre-commit` performs various checks
on all files in PyMongo and uses tools that help follow a consistent
code style within the codebase.
To set up `pre-commit` locally, run:
```bash
brew install pre-commit
pre-commit install
```
To run `pre-commit` manually, run:
```bash
pre-commit run --all-files
```
To run a manual hook like `mypy` manually, run:
```bash
pre-commit run --all-files --hook-stage manual mypy
```
Typically we use `tox` to run the linters, e.g.
```bash
tox -e typecheck-mypy
tox -e lint-manual
```
## Documentation
To contribute to the [API
documentation](https://pymongo.readthedocs.io/en/stable/) just make your
changes to the inline documentation of the appropriate [source
code](https://github.com/mongodb/mongo-python-driver) or [rst
file](https://github.com/mongodb/mongo-python-driver/tree/master/doc) in
a branch and submit a [pull
request](https://help.github.com/articles/using-pull-requests). You
might also use the GitHub
[Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
You can build the documentation locally by running:
```bash
tox -e doc
```
## Running Tests Locally
- Ensure you have started the appropriate Mongo Server(s).
- Run `pip install tox` to use `tox` for testing or run
`pip install -e ".[test]"` to run `pytest` directly.
- Run `tox -m test` or `pytest` to run all of the tests.
- Append `test/<mod_name>.py::<class_name>::<test_name>` to run
specific tests. You can omit the `<test_name>` to test a full class
and the `<class_name>` to test a full module. For example:
`tox -m test test/test_change_stream.py::TestUnifiedChangeStreamsErrors::test_change_stream_errors_on_ElectionInProgress`.
- Use the `-k` argument to select tests by pattern.
## Running Load Balancer Tests Locally
- Install `haproxy` (available as `brew install haproxy` on macOS).
- Clone `drivers-evergreen-tools`:
`git clone git@github.com:mongodb-labs/drivers-evergreen-tools.git`.
- Start the servers using
`LOAD_BALANCER=true TOPOLOGY=sharded_cluster AUTH=noauth SSL=nossl MONGODB_VERSION=6.0 DRIVERS_TOOLS=$PWD/drivers-evergreen-tools MONGO_ORCHESTRATION_HOME=$PWD/drivers-evergreen-tools/.evergreen/orchestration $PWD/drivers-evergreen-tools/.evergreen/run-orchestration.sh`.
- Start the load balancer using:
`MONGODB_URI='mongodb://localhost:27017,localhost:27018/' $PWD/drivers-evergreen-tools/.evergreen/run-load-balancer.sh start`.
- Run the tests from the `pymongo` checkout directory using:
`TEST_LOADBALANCER=1 tox -m test-eg`.
## Re-sync Spec Tests
If you would like to re-sync the copy of the specification tests in the
PyMongo repository with that which is inside the [specifications
repo](https://github.com/mongodb/specifications), please use the script
provided in `.evergreen/resync-specs.sh`.:
```bash
git clone git@github.com:mongodb/specifications.git
export MDB_SPECS=~/specifications
cd ~/mongo-python-driver/.evergreen
./resync-specs.sh -b "<regex>" spec1 spec2 ...
./resync-specs.sh -b "connection-string*" crud bson-corpus # Updates crud and bson-corpus specs while ignoring all files with the regex "connection-string*"
cd ..
```
The `-b` flag adds as a regex pattern to block files you do not wish to
update in PyMongo. This is primarily helpful if you are implementing a
new feature in PyMongo that has spec tests already implemented, or if
you are attempting to validate new spec tests in PyMongo.

171
CONTRIBUTING.rst
View File

@ -1,171 +0,0 @@
Contributing to PyMongo
=======================
PyMongo has a large `community
<https://pymongo.readthedocs.io/en/stable/contributors.html>`_ and
contributions are always encouraged. Contributions can be as simple as
minor tweaks to the documentation. Please read these guidelines before
sending a pull request.
Bugfixes and New Features
-------------------------
Before starting to write code, look for existing `tickets
<https://jira.mongodb.org/browse/PYTHON>`_ or `create one
<https://jira.mongodb.org/browse/PYTHON>`_ for your specific
issue or feature request. That way you avoid working on something
that might not be of interest or that has already been addressed.
Supported Interpreters
----------------------
PyMongo supports CPython 3.7+ and PyPy3.8+. Language
features not supported by all interpreters can not be used.
Style Guide
-----------
PyMongo follows `PEP8 <http://www.python.org/dev/peps/pep-0008/>`_
including 4 space indents and 79 character line limits.
General Guidelines
------------------
- Avoid backward breaking changes if at all possible.
- Write inline documentation for new classes and methods.
- Write tests and make sure they pass (make sure you have a mongod
running on the default port, then execute ``tox -m test``
from the cmd line to run the test suite).
- Add yourself to doc/contributors.rst :)
Authoring a Pull Request
------------------------
**Our Pull Request Policy is based on this** `Code Review Developer Guide <https://google.github.io/eng-practices/review>`_
The expectation for any code author is to provide all the context needed in the space of a
pull request for any engineer to feel equipped to review the code. Depending on the type of
change, do your best to highlight important new functions or objects you’ve introduced in the
code; think complex functions or new abstractions. Whilst it may seem like more work for you to
adjust your pull request, the reality is your likelihood for getting review sooner shoots
up.
**Self Review Guidelines to follow**
- If the PR is too large, split it if possible.
- Use 250 LoC (excluding test data and config changes) as a rule-of-thumb.
- Moving and changing code should be in separate PRs or commits.
- Moving: Taking large code blobs and transplanting them to another file. There's generally no (or very little) actual code changed other than a cut and paste. It can even be extended to large deletions.
- Changing: Adding code changes (be that refactors or functionality additions/subtractions).
- These two, when mixed, can muddy understanding and sometimes make it harder for reviewers to keep track of things.
- Prefer explaining with code comments instead of PR comments.
**Provide background**
- The PR description and linked tickets should answer the "what" and "why" of the change. The code change explains the "how".
**Follow the Template**
- Please do not deviate from the template we make; it is there for a lot of reasons. If it is a one line fix, we still need to have context on what and why it is needed.
- If making a versioning change, please let that be known. See examples below:
- ``versionadded:: 3.11``
- ``versionchanged:: 3.5``
**Pull Request Template Breakdown**
- **Github PR Title**
- The PR Title format should always be ``[JIRA-ID] : Jira Title or Blurb Summary``.
- **JIRA LINK**
- Convenient link to the associated JIRA ticket.
- **Summary**
- Small blurb on why this is needed. The JIRA task should have the more in-depth description, but this should still, at a high level, give anyone looking an understanding of why the PR has been checked in.
- **Changes in this PR**
- The explicit code changes that this PR is introducing. This should be more specific than just the task name. (Unless the task name is very clear).
- **Test Plan**
- Everything needs a test description. Describe what you did to validate your changes actually worked; if you did nothing, then document you did not test it. Aim to make these steps reproducible by other engineers, specifically with your primary reviewer in mind.
- **Screenshots**
- Any images that provide more context to the PR. Usually, these just coincide with the test plan.
- **Callouts or follow-up items**
- This is a good place for identifying “to-dos” that you’ve placed in the code (Must have an accompanying JIRA Ticket).
- Potential bugs that you are unsure how to test in the code.
- Opinions you want to receive about your code.
Running Linters
---------------
PyMongo uses `pre-commit <https://pypi.org/project/pre-commit/>`_
for managing linting of the codebase.
``pre-commit`` performs various checks on all files in PyMongo and uses tools
that help follow a consistent code style within the codebase.
To set up ``pre-commit`` locally, run::
pip install pre-commit
pre-commit install
To run ``pre-commit`` manually, run::
pre-commit run --all-files
To run a manual hook like ``flake8`` manually, run::
pre-commit run --all-files --hook-stage manual flake8
Documentation
-------------
To contribute to the `API documentation <https://pymongo.readthedocs.io/en/stable/>`_
just make your changes to the inline documentation of the appropriate
`source code <https://github.com/mongodb/mongo-python-driver>`_ or `rst file
<https://github.com/mongodb/mongo-python-driver/tree/master/doc>`_ in a
branch and submit a `pull request <https://help.github.com/articles/using-pull-requests>`_.
You might also use the GitHub `Edit <https://github.com/blog/844-forking-with-the-edit-button>`_
button.
Running Tests Locally
---------------------
- Ensure you have started the appropriate Mongo Server(s).
- Run ``pip install tox`` to use ``tox`` for testing or run ``pip install -e ".[test]"`` to run ``pytest`` directly.
- Run ``tox -m test`` or ``pytest`` to run all of the tests.
- Append ``test/<mod_name>.py::<class_name>::<test_name>`` to
run specific tests. You can omit the ``<test_name>`` to test a full class
and the ``<class_name>`` to test a full module. For example:
``tox -m test test/test_change_stream.py::TestUnifiedChangeStreamsErrors::test_change_stream_errors_on_ElectionInProgress``.
- Use the ``-k`` argument to select tests by pattern.
Running Load Balancer Tests Locally
-----------------------------------
- Install ``haproxy`` (available as ``brew install haproxy`` on macOS).
- Clone ``drivers-evergreen-tools``: ``git clone git@github.com:mongodb-labs/drivers-evergreen-tools.git``.
- Start the servers using ``LOAD_BALANCER=true TOPOLOGY=sharded_cluster AUTH=noauth SSL=nossl MONGODB_VERSION=6.0 DRIVERS_TOOLS=$PWD/drivers-evergreen-tools MONGO_ORCHESTRATION_HOME=$PWD/drivers-evergreen-tools/.evergreen/orchestration $PWD/drivers-evergreen-tools/.evergreen/run-orchestration.sh``.
- Start the load balancer using: ``MONGODB_URI='mongodb://localhost:27017,localhost:27018/' $PWD/drivers-evergreen-tools/.evergreen/run-load-balancer.sh start``.
- Run the tests from the ``pymongo`` checkout directory using: ``TEST_LOADBALANCER=1 tox -m test-eg``.
Re-sync Spec Tests
------------------
If you would like to re-sync the copy of the specification tests in the
PyMongo repository with that which is inside the `specifications repo
<https://github.com/mongodb/specifications>`_, please
use the script provided in ``.evergreen/resync-specs.sh``.::
git clone git@github.com:mongodb/specifications.git
export MDB_SPECS=~/specifications
cd ~/mongo-python-driver/.evergreen
./resync-specs.sh -b "<regex>" spec1 spec2 ...
./resync-specs.sh -b "connection-string*" crud bson-corpus # Updates crud and bson-corpus specs while ignoring all files with the regex "connection-string*"
cd ..
The ``-b`` flag adds as a regex pattern to block files you do not wish to
update in PyMongo.
This is primarily helpful if you are implementing a new feature in PyMongo
that has spec tests already implemented, or if you are attempting to
validate new spec tests in PyMongo.

6
MANIFEST.in
View File

@ -1,4 +1,4 @@
include README.rst
include README.md
include LICENSE
include THIRD-PARTY-NOTICES
include *.ini
@ -6,8 +6,8 @@ exclude .coveragerc
exclude .git-blame-ignore-revs
exclude .pre-commit-config.yaml
exclude .readthedocs.yaml
exclude CONTRIBUTING.rst
exclude RELEASE.rst
exclude CONTRIBUTING.md
exclude RELEASE.md
recursive-include doc *.rst
recursive-include doc *.py
recursive-include doc *.conf

229
README.md Normal file
View File

@ -0,0 +1,229 @@
# PyMongo
See [the mongo site](http://www.mongodb.org) for more information.
See [GitHub](http://github.com/mongodb/mongo-python-driver) for the
latest source.
Documentation: available at [pymongo.readthedocs.io](https://pymongo.readthedocs.io/en/stable/)
Author: The MongoDB Python Team
## About
The PyMongo distribution contains tools for interacting with MongoDB
database from Python. The `bson` package is an implementation of the
[BSON format](http://bsonspec.org) for Python. The `pymongo` package is
a native Python driver for MongoDB. The `gridfs` package is a
[gridfs](https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst/)
implementation on top of `pymongo`.
PyMongo supports MongoDB 3.6, 4.0, 4.2, 4.4, 5.0, 6.0, and 7.0.
## Support / Feedback
For issues with, questions about, or feedback for PyMongo, please look
into our [support channels](https://support.mongodb.com/welcome). Please
do not email any of the PyMongo developers directly with issues or
questions - you're more likely to get an answer on
[StackOverflow](https://stackoverflow.com/questions/tagged/mongodb)
(using a "mongodb" tag).
## Bugs / Feature Requests
Think you've found a bug? Want to see a new feature in PyMongo? Please
open a case in our issue management tool, JIRA:
- [Create an account and login](https://jira.mongodb.org).
- Navigate to [the PYTHON
project](https://jira.mongodb.org/browse/PYTHON).
- Click **Create Issue** - Please provide as much information as
possible about the issue type and how to reproduce it.
Bug reports in JIRA for all driver projects (i.e. PYTHON, CSHARP, JAVA)
and the Core Server (i.e. SERVER) project are **public**.
### How To Ask For Help
Please include all of the following information when opening an issue:
- Detailed steps to reproduce the problem, including full traceback,
if possible.
- The exact python version used, with patch level:
```bash
python -c "import sys; print(sys.version)"
```
- The exact version of PyMongo used, with patch level:
```bash
python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
```
- The operating system and version (e.g. Windows 7, OSX 10.8, ...)
- Web framework or asynchronous network library used, if any, with
version (e.g. Django 1.7, mod_wsgi 4.3.0, gevent 1.0.1, Tornado
4.0.2, ...)
### Security Vulnerabilities
If you've identified a security vulnerability in a driver or any other
MongoDB project, please report it according to the [instructions
here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/).
## Installation
PyMongo can be installed with [pip](http://pypi.python.org/pypi/pip):
```bash
python -m pip install pymongo
```
Or `easy_install` from [setuptools](http://pypi.python.org/pypi/setuptools):
```bash
python -m easy_install pymongo
```
You can also download the project source and do:
```bash
pip install .
```
Do **not** install the "bson" package from pypi. PyMongo comes with
its own bson package; running "pip install bson" installs a third-party
package that is incompatible with PyMongo.
## Dependencies
PyMongo supports CPython 3.7+ and PyPy3.7+.
Required dependencies:
Support for `mongodb+srv://` URIs requires [dnspython](https://pypi.python.org/pypi/dnspython)
Optional dependencies:
GSSAPI authentication requires
[pykerberos](https://pypi.python.org/pypi/pykerberos) on Unix or
[WinKerberos](https://pypi.python.org/pypi/winkerberos) on Windows. The
correct dependency can be installed automatically along with PyMongo:
```bash
python -m pip install "pymongo[gssapi]"
```
MONGODB-AWS authentication requires
[pymongo-auth-aws](https://pypi.org/project/pymongo-auth-aws/):
```bash
python -m pip install "pymongo[aws]"
```
OCSP (Online Certificate Status Protocol) requires
[PyOpenSSL](https://pypi.org/project/pyOpenSSL/),
[requests](https://pypi.org/project/requests/),
[service_identity](https://pypi.org/project/service_identity/) and may
require [certifi](https://pypi.python.org/pypi/certifi):
```bash
python -m pip install "pymongo[ocsp]"
```
Wire protocol compression with snappy requires
[python-snappy](https://pypi.org/project/python-snappy):
```bash
python -m pip install "pymongo[snappy]"
```
Wire protocol compression with zstandard requires
[zstandard](https://pypi.org/project/zstandard):
```bash
python -m pip install "pymongo[zstd]"
```
Client-Side Field Level Encryption requires
[pymongocrypt](https://pypi.org/project/pymongocrypt/) and
[pymongo-auth-aws](https://pypi.org/project/pymongo-auth-aws/):
```bash
python -m pip install "pymongo[encryption]"
```
You can install all dependencies automatically with the following
command:
```bash
python -m pip install "pymongo[gssapi,aws,ocsp,snappy,zstd,encryption]"
```
Additional dependencies are:
- (to generate documentation or run tests)
[tox](https://tox.wiki/en/latest/index.html)
## Examples
Here's a basic example (for more see the *examples* section of the
docs):
```pycon
>>> import pymongo
>>> client = pymongo.MongoClient("localhost", 27017)
>>> db = client.test
>>> db.name
'test'
>>> db.my_collection
Collection(Database(MongoClient('localhost', 27017), 'test'), 'my_collection')
>>> db.my_collection.insert_one({"x": 10}).inserted_id
ObjectId('4aba15ebe23f6b53b0000000')
>>> db.my_collection.insert_one({"x": 8}).inserted_id
ObjectId('4aba160ee23f6b543e000000')
>>> db.my_collection.insert_one({"x": 11}).inserted_id
ObjectId('4aba160ee23f6b543e000002')
>>> db.my_collection.find_one()
{'x': 10, '_id': ObjectId('4aba15ebe23f6b53b0000000')}
>>> for item in db.my_collection.find():
... print(item["x"])
...
10
8
11
>>> db.my_collection.create_index("x")
'x_1'
>>> for item in db.my_collection.find().sort("x", pymongo.ASCENDING):
... print(item["x"])
...
8
10
11
>>> [item["x"] for item in db.my_collection.find().limit(2).skip(1)]
[8, 11]
```
## Documentation
Documentation is available at
[pymongo.readthedocs.io](https://pymongo.readthedocs.io/en/stable/).
Documentation can be generated by running **tox -m doc**. Generated
documentation can be found in the `doc/build/html/` directory.
## Learning Resources
- MongoDB Learn - [Python
courses](https://learn.mongodb.com/catalog?labels=%5B%22Language%22%5D&values=%5B%22Python%22%5D).
- [Python Articles on Developer
Center](https://www.mongodb.com/developer/languages/python/).
## Testing
The easiest way to run the tests is to run **tox -m test** in the root
of the distribution. For example,
```bash
tox -e test
```

212
README.rst
View File

@ -1,212 +0,0 @@
=======
PyMongo
=======
:Info: See `the mongo site <http://www.mongodb.org>`_ for more information. See `GitHub <http://github.com/mongodb/mongo-python-driver>`_ for the latest source.
:Documentation: Available at `pymongo.readthedocs.io <https://pymongo.readthedocs.io/en/stable/>`_
:Author: The MongoDB Python Team
About
=====
The PyMongo distribution contains tools for interacting with MongoDB
database from Python. The ``bson`` package is an implementation of
the `BSON format <http://bsonspec.org>`_ for Python. The ``pymongo``
package is a native Python driver for MongoDB. The ``gridfs`` package
is a `gridfs
<https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst/>`_
implementation on top of ``pymongo``.
PyMongo supports MongoDB 3.6, 4.0, 4.2, 4.4, 5.0, 6.0, and 7.0.
Support / Feedback
==================
For issues with, questions about, or feedback for PyMongo, please look into
our `support channels <https://support.mongodb.com/welcome>`_. Please
do not email any of the PyMongo developers directly with issues or
questions - you're more likely to get an answer on `StackOverflow <https://stackoverflow.com/questions/tagged/mongodb>`_
(using a "mongodb" tag).
Bugs / Feature Requests
=======================
Think you’ve found a bug? Want to see a new feature in PyMongo? Please open a
case in our issue management tool, JIRA:
- `Create an account and login <https://jira.mongodb.org>`_.
- Navigate to `the PYTHON project <https://jira.mongodb.org/browse/PYTHON>`_.
- Click **Create Issue** - Please provide as much information as possible about the issue type and how to reproduce it.
Bug reports in JIRA for all driver projects (i.e. PYTHON, CSHARP, JAVA) and the
Core Server (i.e. SERVER) project are **public**.
How To Ask For Help
-------------------
Please include all of the following information when opening an issue:
- Detailed steps to reproduce the problem, including full traceback, if possible.
- The exact python version used, with patch level::
$ python -c "import sys; print(sys.version)"
- The exact version of PyMongo used, with patch level::
$ python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
- The operating system and version (e.g. Windows 7, OSX 10.8, ...)
- Web framework or asynchronous network library used, if any, with version (e.g.
Django 1.7, mod_wsgi 4.3.0, gevent 1.0.1, Tornado 4.0.2, ...)
Security Vulnerabilities
------------------------
If you’ve identified a security vulnerability in a driver or any other
MongoDB project, please report it according to the `instructions here
<https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/>`_.
Installation
============
PyMongo can be installed with `pip <http://pypi.python.org/pypi/pip>`_::
$ python -m pip install pymongo
Or ``easy_install`` from
`setuptools <http://pypi.python.org/pypi/setuptools>`_::
$ python -m easy_install pymongo
You can also download the project source and do::
$ pip install .
Do **not** install the "bson" package from pypi. PyMongo comes with its own
bson package; doing "easy_install bson" installs a third-party package that
is incompatible with PyMongo.
Dependencies
============
PyMongo supports CPython 3.7+ and PyPy3.7+.
Required dependencies:
Support for mongodb+srv:// URIs requires `dnspython
<https://pypi.python.org/pypi/dnspython>`_
Optional dependencies:
GSSAPI authentication requires `pykerberos
<https://pypi.python.org/pypi/pykerberos>`_ on Unix or `WinKerberos
<https://pypi.python.org/pypi/winkerberos>`_ on Windows. The correct
dependency can be installed automatically along with PyMongo::
$ python -m pip install "pymongo[gssapi]"
MONGODB-AWS authentication requires `pymongo-auth-aws
<https://pypi.org/project/pymongo-auth-aws/>`_::
$ python -m pip install "pymongo[aws]"
OCSP (Online Certificate Status Protocol) requires `PyOpenSSL
<https://pypi.org/project/pyOpenSSL/>`_, `requests
<https://pypi.org/project/requests/>`_, `service_identity
<https://pypi.org/project/service_identity/>`_ and may
require `certifi
<https://pypi.python.org/pypi/certifi>`_::
$ python -m pip install "pymongo[ocsp]"
Wire protocol compression with snappy requires `python-snappy
<https://pypi.org/project/python-snappy>`_::
$ python -m pip install "pymongo[snappy]"
Wire protocol compression with zstandard requires `zstandard
<https://pypi.org/project/zstandard>`_::
$ python -m pip install "pymongo[zstd]"
Client-Side Field Level Encryption requires `pymongocrypt
<https://pypi.org/project/pymongocrypt/>`_ and
`pymongo-auth-aws <https://pypi.org/project/pymongo-auth-aws/>`_::
$ python -m pip install "pymongo[encryption]"
You can install all dependencies automatically with the following
command::
$ python -m pip install "pymongo[gssapi,aws,ocsp,snappy,zstd,encryption]"
Additional dependencies are:
- (to generate documentation or run tests) tox_
Examples
========
Here's a basic example (for more see the *examples* section of the docs):
.. code-block:: pycon
>>> import pymongo
>>> client = pymongo.MongoClient("localhost", 27017)
>>> db = client.test
>>> db.name
'test'
>>> db.my_collection
Collection(Database(MongoClient('localhost', 27017), 'test'), 'my_collection')
>>> db.my_collection.insert_one({"x": 10}).inserted_id
ObjectId('4aba15ebe23f6b53b0000000')
>>> db.my_collection.insert_one({"x": 8}).inserted_id
ObjectId('4aba160ee23f6b543e000000')
>>> db.my_collection.insert_one({"x": 11}).inserted_id
ObjectId('4aba160ee23f6b543e000002')
>>> db.my_collection.find_one()
{'x': 10, '_id': ObjectId('4aba15ebe23f6b53b0000000')}
>>> for item in db.my_collection.find():
... print(item["x"])
...
10
8
11
>>> db.my_collection.create_index("x")
'x_1'
>>> for item in db.my_collection.find().sort("x", pymongo.ASCENDING):
... print(item["x"])
...
8
10
11
>>> [item["x"] for item in db.my_collection.find().limit(2).skip(1)]
[8, 11]
Documentation
=============
Documentation is available at `pymongo.readthedocs.io <https://pymongo.readthedocs.io/en/stable/>`_.
Documentation can be generated by running **tox -m doc**. Generated documentation can be found in the
*doc/build/html/* directory.
Learning Resources
==================
MongoDB Learn - `Python courses <https://learn.mongodb.com/catalog?labels=%5B%22Language%22%5D&values=%5B%22Python%22%5D>`_.
`Python Articles on Developer Center <https://www.mongodb.com/developer/languages/python/>`_.
Testing
=======
The easiest way to run the tests is to run **tox -m test** in
the root of the distribution.
To verify that PyMongo works with Gevent's monkey-patching::
$ python green_framework_test.py gevent
Or with Eventlet's::
$ python green_framework_test.py eventlet
.. _tox: https://tox.wiki/en/latest/index.html

89
RELEASE.md Normal file
View File

@ -0,0 +1,89 @@
# Some notes on PyMongo releases
## Versioning
We follow [semver](https://semver.org/) and [pep-0440](https://www.python.org/dev/peps/pep-0440)
for versioning.
We shoot for a release every few months - that will generally just
increment the middle / minor version number (e.g. `3.5.0` -> `3.6.0`).
Patch releases are reserved for bug fixes (in general no new features or
deprecations) - they only happen in cases where there is a critical bug
in a recently released version, or when a release has no new features or
API changes.
In between releases we add `.devN` to the version number to denote the
version under development. So if we just released `3.6.0`, then the
current dev version might be `3.6.1.dev0` or `3.7.0.dev0`. When we make the
next release we replace all instances of `3.x.x.devN` in the docs with the
new version number.
## Deprecation
Changes should be backwards compatible unless absolutely necessary. When
making API changes the approach is generally to add a deprecation
warning but keeping the existing API functional. Deprecated features can
be removed in a release that changes the major version number.
## Doing a Release
1. PyMongo is tested on Evergreen. Ensure the latest commit are passing
[CI](https://spruce.mongodb.com/commits/mongo-python-driver) as expected.
2. Check Jira to ensure all the tickets in this version have been
completed.
3. Add release notes to `doc/changelog.rst`. Generally just
summarize/clarify the git log, but you might add some more long form
notes for big changes.
4. Make sure version number is updated in `pymongo/_version.py`
5. Commit with a BUMP version_number message, eg
`git commit -m 'BUMP 3.11.0'`.
6. Tag w/ version_number, eg,
`git tag -a '3.11.0' -m 'BUMP 3.11.0' <COMMIT>`.
7. Bump the version number to `<next version>.dev0` in
`pymongo/_version.py`, commit, push.
8. Push commit / tag, eg `git push && git push --tags`.
9. Pushing a tag will trigger a release process in Evergreen which
builds wheels for manylinux, macOS, and Windows. Wait for the
"release-combine" task to complete and then download the "Release
files all" archive. See https://spruce.mongodb.com/commits/mongo-python-driver?buildVariants=release&view=ALL
The contents should look like this:
$ ls path/to/archive
pymongo-<version>-cp310-cp310-macosx_10_9_universal2.whl
...
pymongo-<version>-cp38-cp38-manylinux2014_x86_64.whl
...
pymongo-<version>-cp38-cp38-win_amd64.whl
...
pymongo-<version>.tar.gz
10. Upload all the release packages to PyPI with twine:
$ python3 -m twine upload path/to/archive/*
11. Make sure the new version appears on
`https://pymongo.readthedocs.io/en/stable/`. If the new version does not show
up automatically, trigger a rebuild of "latest" on https://readthedocs.org/projects/pymongo/builds/.
12. Publish the release version in Jira and add a description of the release, such as a the reason
or the main feature.
13. Announce the release on the [community forum](https://www.mongodb.com/community/forums/tags/c/announcements/driver-releases/110/python)
14. File a ticket for DOCSP highlighting changes in server version and
Python version compatibility or the lack thereof, for example https://jira.mongodb.org/browse/DOCSP-34040
15. Create a GitHub Release for the tag using https://github.com/mongodb/mongo-python-driver/releases/new.
The title should be "PyMongo X.Y.Z", and the description should
contain a link to the release notes on the the community forum, e.g.
"Release notes: mongodb.com/community/forums/t/pymongo-4-0-2-released/150457"

90
RELEASE.rst
View File

@ -1,90 +0,0 @@
Some notes on PyMongo releases
==============================
Versioning
----------
We shoot for a release every few months - that will generally just
increment the middle / minor version number (e.g. 3.5.0 -> 3.6.0).
Patch releases are reserved for bug fixes (in general no new features
or deprecations) - they only happen in cases where there is a critical
bug in a recently released version, or when a release has no new
features or API changes.
In between releases we add .devN to the version number to denote the version
under development. So if we just released 3.6.0, then the current dev
version might be 3.6.1.dev0 or 3.7.0.dev0. When we make the next release we
replace all instances of 3.x.x.devN in the docs with the new version number.
https://semver.org/
https://www.python.org/dev/peps/pep-0440/
Deprecation
-----------
Changes should be backwards compatible unless absolutely necessary. When making
API changes the approach is generally to add a deprecation warning but keeping
the existing API functional. Deprecated features can be removed in a release
that changes the major version number.
Doing a Release
---------------
1. PyMongo is tested on Evergreen. Ensure the latest commit are passing CI
as expected: https://evergreen.mongodb.com/waterfall/mongo-python-driver.
2. Check Jira to ensure all the tickets in this version have been completed.
3. Add release notes to doc/changelog.rst. Generally just summarize/clarify
the git log, but you might add some more long form notes for big changes.
4. Make sure version number is updated in ``pymongo/_version.py``
5. Commit with a BUMP version_number message, eg ``git commit -m 'BUMP 3.11.0'``.
6. Tag w/ version_number, eg, ``git tag -a '3.11.0' -m 'BUMP 3.11.0' <COMMIT>``.
7. Push commit / tag, eg ``git push && git push --tags``.
8. Pushing a tag will trigger a release process in Evergreen which builds
wheels for manylinux, macOS, and Windows. Wait for the "release-combine"
task to complete and then download the "Release files all" archive. See:
https://evergreen.mongodb.com/waterfall/mongo-python-driver?bv_filter=release
The contents should look like this::
$ ls path/to/archive
pymongo-<version>-cp310-cp310-macosx_10_9_universal2.whl
...
pymongo-<version>-cp38-cp38-manylinux2014_x86_64.whl
...
pymongo-<version>-cp38-cp38-win_amd64.whl
...
pymongo-<version>.tar.gz
9. Upload all the release packages to PyPI with twine::
$ python3 -m twine upload path/to/archive/*
10. Make sure the new version appears on https://pymongo.readthedocs.io/. If the
new version does not show up automatically, trigger a rebuild of "latest":
https://readthedocs.org/projects/pymongo/builds/
11. Bump the version number to <next version>.dev0 in ``pymongo/_version.py``,
commit, push.
12. Publish the release version in Jira.
13. Announce the release on:
https://www.mongodb.com/community/forums/tags/c/announcements/driver-releases/110/python
14. File a ticket for DOCSP highlighting changes in server version and Python
version compatibility or the lack thereof, for example:
https://jira.mongodb.org/browse/DOCSP-34040
15. Create a GitHub Release for the tag using
https://github.com/mongodb/mongo-python-driver/releases/new.
The title should be "PyMongo X.Y.Z", and the description should contain
a link to the release notes on the the community forum, e.g.
"Release notes: mongodb.com/community/forums/t/pymongo-4-0-2-released/150457."

2
pyproject.toml
View File

@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
name = "pymongo"
dynamic = ["version"]
description = "Python driver for MongoDB <http://www.mongodb.org>"
readme = "README.rst"
readme = "README.md"
license = {file="LICENSE"}
requires-python = ">=3.7"
authors = [