diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..bf25f0af4 --- /dev/null +++ b/CONTRIBUTING.md @@ -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/.py::::` to run + specific tests. You can omit the `` to test a full class + and the `` 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 "" 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. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 07d6f1d77..000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,171 +0,0 @@ -Contributing to PyMongo -======================= - -PyMongo has a large `community -`_ 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 -`_ or `create one -`_ 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 `_ -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 `_ - -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 `_ -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 `_ -just make your changes to the inline documentation of the appropriate -`source code `_ or `rst file -`_ in a -branch and submit a `pull request `_. -You might also use the GitHub `Edit `_ -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/.py::::`` to - run specific tests. You can omit the ```` to test a full class - and the ```` 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 -`_, 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 "" 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. diff --git a/MANIFEST.in b/MANIFEST.in index 710eae898..b74a716df 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 000000000..8ae5ebdf6 --- /dev/null +++ b/README.md @@ -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 +``` diff --git a/README.rst b/README.rst deleted file mode 100644 index 3172ecb8a..000000000 --- a/README.rst +++ /dev/null @@ -1,212 +0,0 @@ -======= -PyMongo -======= -:Info: See `the mongo site `_ for more information. See `GitHub `_ for the latest source. -:Documentation: Available at `pymongo.readthedocs.io `_ -: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 `_ for Python. The ``pymongo`` -package is a native Python driver for MongoDB. The ``gridfs`` package -is a `gridfs -`_ -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 `_. Please -do not email any of the PyMongo developers directly with issues or -questions - you're more likely to get an answer on `StackOverflow `_ -(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 `_. -- Navigate to `the PYTHON project `_. -- 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 -`_. - -Installation -============ - -PyMongo can be installed with `pip `_:: - - $ python -m pip install pymongo - -Or ``easy_install`` from -`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 -`_ - -Optional dependencies: - -GSSAPI authentication requires `pykerberos -`_ on Unix or `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 -`_:: - - $ python -m pip install "pymongo[aws]" - -OCSP (Online Certificate Status Protocol) requires `PyOpenSSL -`_, `requests -`_, `service_identity -`_ and may -require `certifi -`_:: - - $ python -m pip install "pymongo[ocsp]" - -Wire protocol compression with snappy requires `python-snappy -`_:: - - $ python -m pip install "pymongo[snappy]" - -Wire protocol compression with zstandard requires `zstandard -`_:: - - $ python -m pip install "pymongo[zstd]" - -Client-Side Field Level Encryption requires `pymongocrypt -`_ and -`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 `_. - -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 `_. -`Python Articles on Developer Center `_. - -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 diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..05d7c8d63 --- /dev/null +++ b/RELEASE.md @@ -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' `. + +7. Bump the version number to `.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--cp310-cp310-macosx_10_9_universal2.whl + ... + pymongo--cp38-cp38-manylinux2014_x86_64.whl + ... + pymongo--cp38-cp38-win_amd64.whl + ... + pymongo-.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" diff --git a/RELEASE.rst b/RELEASE.rst deleted file mode 100644 index cabddef84..000000000 --- a/RELEASE.rst +++ /dev/null @@ -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' ``. - -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--cp310-cp310-macosx_10_9_universal2.whl - ... - pymongo--cp38-cp38-manylinux2014_x86_64.whl - ... - pymongo--cp38-cp38-win_amd64.whl - ... - pymongo-.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 .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." diff --git a/pyproject.toml b/pyproject.toml index f70684ede..db2c95669 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" name = "pymongo" dynamic = ["version"] description = "Python driver for MongoDB " -readme = "README.rst" +readme = "README.md" license = {file="LICENSE"} requires-python = ">=3.7" authors = [