mirror of
https://github.com/jazzband/contextlib2.git
synced 2026-03-16 21:50:24 +00:00
f64cf04df8
* generated new diff files covering this sync * added some helper scripts for the sync process * fixed RTD theme regression (due to RTD changes since the last release) Closes #43
102 lines
3.9 KiB
ReStructuredText
102 lines
3.9 KiB
ReStructuredText
.. image:: https://jazzband.co/static/img/badge.svg
|
|
:target: https://jazzband.co/
|
|
:alt: Jazzband
|
|
|
|
.. image:: https://github.com/jazzband/contextlib2/workflows/Test/badge.svg
|
|
:target: https://github.com/jazzband/contextlib2/actions
|
|
:alt: Tests
|
|
|
|
.. image:: https://codecov.io/gh/jazzband/contextlib2/branch/master/graph/badge.svg
|
|
:target: https://codecov.io/gh/jazzband/contextlib2
|
|
:alt: Coverage
|
|
|
|
.. image:: https://readthedocs.org/projects/contextlib2/badge/?version=latest
|
|
:target: https://contextlib2.readthedocs.org/
|
|
:alt: Latest Docs
|
|
|
|
contextlib2 is a backport of the `standard library's contextlib
|
|
module <https://docs.python.org/3/library/contextlib.html>`_ to
|
|
earlier Python versions.
|
|
|
|
It also sometimes serves as a real world proving ground for possible future
|
|
enhancements to the standard library version.
|
|
|
|
Licensing
|
|
---------
|
|
|
|
As a backport of Python standard library software, the implementation, test
|
|
suite and other supporting files for this project are distributed under the
|
|
Python Software License used for the CPython reference implementation.
|
|
|
|
The one exception is the included type hints file, which comes from the
|
|
``typeshed`` project, and is hence distributed under the Apache License 2.0.
|
|
|
|
Development
|
|
-----------
|
|
|
|
``contextlib2`` has no runtime dependencies, but requires ``setuptools`` and
|
|
``wheel`` at build time to generate universal wheel archives.
|
|
|
|
Local testing is a matter of running::
|
|
|
|
python3 -m unittest discover -t . -s test
|
|
|
|
You can test against multiple versions of Python with
|
|
`tox <https://tox.testrun.org/>`_::
|
|
|
|
pip install tox
|
|
tox
|
|
|
|
Versions currently tested in both tox and GitHub Actions are:
|
|
|
|
* CPython 3.8
|
|
* CPython 3.9
|
|
* CPython 3.10
|
|
* CPython 3.11
|
|
* CPython 3.12
|
|
* PyPy3 (specifically 3.10 in GitHub Actions)
|
|
|
|
Updating to a new stdlib reference version
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
As of Python 3.12.3, 4 files needed to be copied from the CPython reference
|
|
implementation to contextlib2:
|
|
|
|
* ``Doc/library/contextlib.rst`` -> ``docs/contextlib2.rst``
|
|
* ``Lib/contextlib.py`` -> ``contextlib2/__init__.py``
|
|
* ``Lib/test/test_contextlib.py`` -> ``test/test_contextlib.py``
|
|
* ``Lib/test/test_contextlib_async.py`` -> ``test/test_contextlib_async.py``
|
|
|
|
The corresponding version of ``contextlib2/__init__.pyi`` also needs to be
|
|
retrieved from the ``typeshed`` project::
|
|
|
|
wget https://raw.githubusercontent.com/python/typeshed/master/stdlib/contextlib.pyi
|
|
|
|
The following patch files are saved in the ``dev`` directory:
|
|
|
|
* changes to ``contextlib2/__init__.py`` to get it to run on the older
|
|
versions (and to add back in the deprecated APIs that never graduated to
|
|
the standard library version)
|
|
* changes to ``test/test_contextlib.py`` and ``test/test_contextlib_async.py``
|
|
to get them to run on the older versions
|
|
* changes to ``contextlib2/__init__.pyi`` to make the Python version
|
|
guards unconditional (since the ``contextlib2`` API is the same on all
|
|
supported versions)
|
|
* changes to ``docs/contextlib2.rst`` to use ``contextlib2`` version
|
|
numbers in the version added/changed notes and to integrate the module
|
|
documentation with the rest of the project documentation
|
|
|
|
When the upstream changes between releases are minor, these patch files may be
|
|
used directly to reapply the ``contextlib2`` specific changes after syncing a
|
|
new version. Even when the patches do not apply cleanly, they're still a useful
|
|
guide as to the changes that are needed to restore compatibility with older
|
|
Python versions and make any other ``contextlib2`` specific updates.
|
|
|
|
The test directory is laid out so that the test suite's imports from
|
|
``test.support`` work the same way as they do in the main CPython test suite.
|
|
These files are selective copies rather than complete ones as the ``contextlib``
|
|
tests only need a tiny fraction of the features available in the real
|
|
``test.support`` module.
|
|
|
|
The ``dev/sync_from_cpython.sh`` and ``dev/save_diff_snapshot.sh`` scripts
|
|
automate some of the steps in the sync process.
|