pax_global_header 0000666 0000000 0000000 00000000064 14745661623 0014530 g ustar 00root root 0000000 0000000 52 comment=3f67ca71143479ef7ce71786538b2bc0ef9ee4b4
deprecated-1.2.18/ 0000775 0000000 0000000 00000000000 14745661623 0013721 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/.bumpversion.cfg 0000664 0000000 0000000 00000001406 14745661623 0017032 0 ustar 00root root 0000000 0000000 [bumpversion]
current_version = 1.2.18
commit = True
tag = False
message = Prepare next version {new_version} (unreleased)
[bumpversion:file:setup.py]
search = version="{current_version}"
replace = version="{new_version}"
[bumpversion:file:deprecated/__init__.py]
search = __version__ = "{current_version}"
replace = __version__ = "{new_version}"
[bumpversion:file:docs/source/conf.py]
search = release = "{current_version}"
replace = release = "{new_version}"
[bumpversion:file:python-deprecated.spec]
search = Version: {current_version}
replace = Version: {new_version}
[bumpversion:file:docs/source/_static/rusty-tools-background.svg]
search = id="deprecated-version">v{current_version}
replace = id="deprecated-version">v{new_version}
deprecated-1.2.18/.editorconfig 0000664 0000000 0000000 00000000367 14745661623 0016404 0 ustar 00root root 0000000 0000000 # see http://editorconfig.org
root = true
[*]
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4
charset = utf-8
[*.{yml,yaml}]
indent_size = 2
[*.{bat,cmd,ps1}]
end_of_line = crlf
deprecated-1.2.18/.github/ 0000775 0000000 0000000 00000000000 14745661623 0015261 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/.github/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000006324 14745661623 0020065 0 ustar 00root root 0000000 0000000 # Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [Laurent LAPORTE](mailto:laurent.laporte.pro@gmail.com). All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org
deprecated-1.2.18/.github/ISSUE_TEMPLATE.md 0000664 0000000 0000000 00000001505 14745661623 0017767 0 ustar 00root root 0000000 0000000 **This issue tracker is a tool to address bugs in Deprecated itself.
Please use Stack Overflow for general questions about using Deprecated
or issues not related to Deprecated Library.**
If you'd like to report a bug in Deprecated, fill out the template below. Provide
any extra information that may be useful/related to your problem.
Ideally, create an [Minimal, Complete, and Verifiable example](http://stackoverflow.com/help/mcve),
which helps us understand the problem and helps check that it is not caused by something in your code.
---
### Expected Behavior
Tell us what should happen.
```python
# Paste a minimal example that causes the problem.
```
### Actual Behavior
Tell us what happens instead.
```pytb
Paste the full traceback if there was an exception.
```
### Environment
* Python version:
* Deprecated version:
deprecated-1.2.18/.github/PULL_REQUEST_TEMPLATE.md 0000664 0000000 0000000 00000001000 14745661623 0021051 0 ustar 00root root 0000000 0000000 Describe what this patch does to fix the issue.
Link to any relevant issues or pull requests.
deprecated-1.2.18/.github/workflows/ 0000775 0000000 0000000 00000000000 14745661623 0017316 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/.github/workflows/codeql-analysis.yml 0000664 0000000 0000000 00000004617 14745661623 0023141 0 ustar 00root root 0000000 0000000 # For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL"
on:
push:
branches: [ master ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ master ]
schedule:
- cron: '22 8 * * 1'
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: false
matrix:
language: [ 'python' ]
# CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
# Learn more:
# https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
steps:
- name: Checkout repository
uses: actions/checkout@v4
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# queries: ./path/to/local/query, your-org/your-repo/queries@main
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@v1
# ℹ️ Command-line programs to run using the OS shell.
# 📚 https://git.io/JvXDl
# ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
# and modify them (or add more) to build your code if your project
# uses a compiled language
#- run: |
# make bootstrap
# make release
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1
deprecated-1.2.18/.github/workflows/python-package.yml 0000664 0000000 0000000 00000002003 14745661623 0022746 0 ustar 00root root 0000000 0000000 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
name: Python package
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
jobs:
pytest:
strategy:
fail-fast: false
matrix:
platform: [ ubuntu-latest, macos-latest, windows-latest ]
python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
runs-on: ${{ matrix.platform }}
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install pytest setuptools
python -m pip install -e .
- name: Test with pytest
run: |
pytest tests/
deprecated-1.2.18/.gitignore 0000664 0000000 0000000 00000007021 14745661623 0015711 0 ustar 00root root 0000000 0000000 ### Python template
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
.idea/
### macOS template
# General
.DS_Store
.AppleDouble
.LSOverride
# Icon must end with two \r
Icon?
![iI]con[_a-zA-Z0-9]
# Thumbnails
._*
# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent
# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk
deprecated-1.2.18/.packit.yml 0000664 0000000 0000000 00000000642 14745661623 0015777 0 ustar 00root root 0000000 0000000 files_to_sync:
- python-deprecated.spec
- .packit.yml
upstream_package_name: Deprecated
upstream_tag_template: v{version}
downstream_package_name: python-deprecated
jobs:
- job: propose_downstream
trigger: release
metadata:
dist_git_branches:
- fedora-all
- job: copr_build
trigger: pull_request
metadata:
targets:
- fedora-all
srpm_build_deps:
- python3-pip
- python3-setuptools_scm
deprecated-1.2.18/.readthedocs.yaml 0000664 0000000 0000000 00000001640 14745661623 0017151 0 ustar 00root root 0000000 0000000 # Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true
# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub
# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: docs/requirements.txt
deprecated-1.2.18/CHANGELOG.rst 0000664 0000000 0000000 00000032307 14745661623 0015747 0 ustar 00root root 0000000 0000000 =========
Changelog
=========
All notable changes to this project will be documented in this file.
The format is based on `Keep a Changelog `_
and this project adheres to `Semantic Versioning `_.
.. note::
The library **"Python-Deprecated"** was renamed **"Deprecated"**, simply!
This project is more consistent because now, the name of the library is the same as the name of the Python package.
- In your ``setup.py``, you can replace the "Python-Deprecated" dependency with "Deprecated".
- In your source code, nothing has changed, you will always use ``import deprecated``, as before.
- I decided to keep the same version number because there is really no change in the source code
(only in comment or documentation).
v1.2.18 (2024-01-25)
====================
This version does not bring any change in the source code, but fixes the build anomaly on Fedora (Packit).
The package must be published on PyPi using `twine `_ to correctly deal with the license file.
v1.2.17 (2024-01-25)
====================
Bug fix release
v1.2.16 (2025-01-24)
====================
Bug fix release
Fix
---
- Fix #78: Fix configuration for Packit 1.0.0
- Fix #79: Fix the configuration for the intersphinx mapping in the Sphinx documentation.
See `How to link to other documentation projects with Intersphinx `_.
Other
-----
- Drop support for Python older than 3.7 in GitHub Actions.
v1.2.15 (2024-11-15)
====================
Bug fix release
Fix
---
- Resolve Python 2.7 support issue introduced in v1.2.14 in ``sphinx.py``.
- Fix #69: Add ``extra_stacklevel`` argument for interoperating with other wrapper functions (refer to #68 for a concrete use case).
- Fix #73: Update class method deprecation warnings for Python 3.13.
- Fix #75: Update GitHub workflows and fix development dependencies for Python 3.12.
Other
-----
- Fix #66: discontinue TravisCI and AppVeyor due to end of free support.
v1.2.14 (2023-05-27)
====================
Bug fix release
Fix
---
- Fix #60: return a correctly dedented docstring when long docstring are using the D212 or D213 format.
Other
-----
- Add support for Python 3.11.
- Drop support for Python older than 3.7 in build systems like pytest and tox,
while ensuring the library remains production-compatible.
- Update GitHub workflow to run in recent Python versions.
v1.2.13 (2021-09-05)
====================
Bug fix release
Fix
---
- Fix #45: Change the signature of the :func:`~deprecated.sphinx.deprecated` decorator to reflect
the valid use cases.
- Fix #48: Fix ``versionadded`` and ``versionchanged`` decorators: do not return a decorator factory,
but a Wrapt adapter.
Other
-----
- Fix configuration for AppVeyor: simplify the test scripts and set the version format to match the current version.
- Change configuration for Tox:
+ change the requirements for ``pip`` to "pip >= 9.0.3, < 21" (Python 2.7, 3.4 and 3.5).
+ install ``typing`` when building on Python 3.4 (required by Pytest->Attrs).
+ run unit tests on Wrapt 1.13 (release candidate).
- Migrating project to `travis-ci.com `_.
v1.2.12 (2021-03-13)
====================
Bug fix release
Fix
---
- Avoid "Explicit markup ends without a blank line" when the decorated function has no docstring.
- Fix #40: 'version' argument is required in Sphinx directives.
- Fix #41: :mod:`deprecated.sphinx`: strip Sphinx cross-referencing syntax from warning message.
Other
-----
- Change in Tox and Travis CI configurations: enable unit testing on Python 3.10.
v1.2.11 (2021-01-17)
====================
Bug fix release
Fix
---
- Fix packit configuration: use ``upstream_tag_template: v{version}``.
- Fix #33: Change the class :class:`~deprecated.sphinx.SphinxAdapter`:
add the ``line_length`` keyword argument to the constructor to specify the max line length of the directive text.
Sphinx decorators also accept the ``line_length`` argument.
- Fix #34: ``versionadded`` and ``versionchanged`` decorators don't emit ``DeprecationWarning``
anymore on decorated classes.
Other
-----
- Change the Tox configuration to run tests on Python 2.7, Python 3.4 and above (and PyPy 2.7 & 3.6).
- Update the classifiers in ``setup.py``.
- Replace ``bumpversion`` by `bump2version `_ in ``setup.py`` and documentation.
- Update configuration for Black and iSort.
- Fix the development requirement versions in ``setup.py`` for Python 2.7 EOL.
v1.2.10 (2020-05-13)
====================
Bug fix release
Fix
---
- Fix #25: ``@deprecated`` respects global warning filters with actions other than "ignore" and "always" on Python 3.
Other
-----
- Change the configuration for TravisCI to build on pypy and pypy3.
- Change the configuration for TravisCI and AppVeyor: drop configuration for Python **3.4** and add **3.8**.
v1.2.9 (2020-04-10)
===================
Bug fix release
Fix
---
- Fix #20: Set the :func:`warnings.warn` stacklevel to 2 if the Python implementation is `PyPy `_.
- Fix packit configuration: use ``dist-git-branch: fedora-all``.
Other
-----
- Change the Tox configuration to run tests on PyPy v2.7 and 3.6.
v1.2.8 (2020-04-05)
===================
Bug fix release
Fix
---
- Fix #15: The ``@deprecated`` decorator doesn't set a warning filter if the *action* keyword argument is
not provided or ``None``. In consequences, the warning messages are only emitted if the global filter allow it.
For more information, see `The Warning Filter `_
in the Python documentation.
- Fix #13: Warning displays the correct filename and line number when decorating a class if wrapt
does not have the compiled c extension.
Documentation
-------------
- The :ref:`api` documentation and the :ref:`tutorial` is improved to explain how to use
custom warning categories and local filtering (warning filtering at function call).
- Fix #17: Customize the sidebar to add links to the documentation to the source in GitHub and to the Bug tracker.
Add a logo in the sidebar and change the logo in the main page to see the library version.
- Add a detailed documentation about :ref:`sphinx_deco`.
Other
-----
- Change the Tox configuration to test the library with Wrapt 1.12.x.
v1.2.7 (2019-11-11)
===================
Bug fix release
Fix
---
- Fix #13: Warning displays the correct filename and line number when decorating a function if wrapt
does not have the compiled c extension.
Other
-----
- Support packit for Pull Request tests and sync to Fedora (thanks to Petr Hráček).
Supported since v1.2.6.
- Add `Black `_ configuration file.
v1.2.6 (2019-07-06)
===================
Bug fix release
Fix
---
- Fix #9: Change the project's configuration: reinforce the constraint to the Wrapt requirement.
Other
-----
- Upgrade project configuration (``setup.py``) to add the *project_urls* property:
Documentation, Source and Bug Tracker URLs.
- Change the Tox configuration to test the library against different Wrapt versions.
- Fix an issue with the AppVeyor build: upgrade setuptools version in ``appveyor.yml``,
change the Tox configuration: set ``py27,py34,py35: pip >= 9.0.3, < 19.2``.
v1.2.5 (2019-02-28)
===================
Bug fix release
Fix
---
- Fix #6: Use :func:`inspect.isroutine` to check if the wrapped object is a user-defined or built-in function or method.
Other
-----
- Upgrade Tox configuration to add support for Python 3.7.
Also, fix PyTest version for Python 2.7 and 3.4 (limited support).
Remove dependency 'requests[security]': useless to build documentation.
- Upgrade project configuration (``setup.py``) to add support for Python 3.7.
v1.2.4 (2018-11-03)
===================
Bug fix release
Fix
---
- Fix #4: Correct the class :class:`~deprecated.classic.ClassicAdapter`:
Don't pass arguments to :meth:`object.__new__` (other than *cls*).
Other
-----
- Add missing docstring to the classes :class:`~deprecated.classic.ClassicAdapter`
and :class:`~deprecated.sphinx.SphinxAdapter`.
- Change the configuration for TravisCI and AppVeyor:
drop configuration for Python **2.6** and **3.3**.
add configuration for Python **3.7** (if available).
.. note::
Deprecated is no more tested with Python **2.6** and **3.3**.
Those Python versions are EOL for some time now and incur incompatibilities
with Continuous Integration tools like TravisCI and AppVeyor.
However, this library should still work perfectly...
v1.2.3 (2018-09-12)
===================
Bug fix release
Fix
---
- Fix #3: ``deprecated.sphinx`` decorators don't update the docstring.
v1.2.2 (2018-09-04)
===================
Bug fix release
Fix
---
- Fix #2: a deprecated class is a class (not a function). Any subclass of a deprecated class is also deprecated.
- Minor fix: add missing documentation in :mod:`deprecated.sphinx` module.
v1.2.1 (2018-08-27)
===================
Bug fix release
Fix
---
- Add a ``MANIFEST.in`` file to package additional files like "LICENSE.rst" in the source distribution.
v1.2.0 (2018-04-02)
===================
Minor release
Added
-----
- Add decorators for Sphinx directive integration: ``versionadded``, ``versionchanged``, ``deprecated``.
That way, the developer can document the changes.
Changed
-------
- Add the ``version`` parameter to the ``@deprecated`` decorator:
used to specify the starting version number of the deprecation.
- Add a way to choose a ``DeprecationWarning`` subclass.
Removed
-------
- Deprecated no longer supports Python **2.6** and **3.3**. Those Python versions
are EOL for some time now and incur maintenance and compatibility costs on
the Deprecated core team, and following up with the rest of the community we
decided that they will no longer be supported starting on this version. Users
which still require those versions should pin Deprecated to ``< 1.2``.
v1.1.5 (2019-02-28)
===================
Bug fix release
Fix
---
- Fix #6: Use :func:`inspect.isroutine` to check if the wrapped object is a user-defined or built-in function or method.
Other
-----
- Upgrade Tox configuration to add support for Python 3.7.
Also, fix PyTest version for Python 2.7 and 3.4 (limited support).
Remove dependency 'requests[security]': useless to build documentation.
- Upgrade project configuration (``setup.py``) to add support for Python 3.7.
v1.1.4 (2018-11-03)
===================
Bug fix release
Fix
---
- Fix #4: Correct the function :func:`~deprecated.deprecated`:
Don't pass arguments to :meth:`object.__new__` (other than *cls*).
Other
-----
- Change the configuration for TravisCI and AppVeyor:
drop configuration for Python **2.6** and **3.3**.
add configuration for Python **3.7**.
.. note::
Deprecated is no more tested with Python **2.6** and **3.3**.
Those Python versions are EOL for some time now and incur incompatibilities
with Continuous Integration tools like TravisCI and AppVeyor.
However, this library should still work perfectly...
v1.1.3 (2018-09-03)
===================
Bug fix release
Fix
---
- Fix #2: a deprecated class is a class (not a function). Any subclass of a deprecated class is also deprecated.
v1.1.2 (2018-08-27)
===================
Bug fix release
Fix
---
- Add a ``MANIFEST.in`` file to package additional files like "LICENSE.rst" in the source distribution.
v1.1.1 (2018-04-02)
===================
Bug fix release
Fix
---
- Minor correction in ``CONTRIBUTING.rst`` for Sphinx builds: add the ``-d`` option to put apart the ``doctrees``
from the generated documentation and avoid warnings with epub generator.
- Fix in documentation configuration: remove hyphens in ``epub_identifier`` (ISBN number has no hyphens).
- Fix in Tox configuration: set the versions interval of each dependency.
Other
-----
- Change in documentation: improve sentence phrasing in the Tutorial.
- Restore the epub title to "Python Deprecated Library v1.1 Documentation" (required for Lulu.com).
v1.1.0 (2017-11-06)
===================
Minor release
Added
-----
- Change in :func:`deprecated.deprecated` decorator: you can give a "reason" message
to help the developer choose another class, function or method.
- Add support for Universal Wheel (Python versions 2.6, 2.7, 3.3, 3.4, 3.5, 3.6 and PyPy).
- Add missing ``__doc__`` and ``__version__`` attributes to :mod:`deprecated` module.
- Add an extensive documentation of Deprecated Library.
Other
-----
- Improve `Travis `_ configuration file (compatibility from Python 2.6 to 3.7-dev, and PyPy).
- Add `AppVeyor `_ configuration file.
- Add `Tox `_ configuration file.
- Add `BumpVersion `_ configuration file.
- Improve project settings: add a long description for the project.
Set the **license** and the **development status** in the classifiers property.
- Add the :file:`CONTRIBUTING.rst` file: "How to contribute to Deprecated Library".
v1.0.0 (2016-08-30)
===================
Major release
Added
-----
- **deprecated**: Created **@deprecated** decorator
deprecated-1.2.18/CONTRIBUTING.rst 0000664 0000000 0000000 00000012347 14745661623 0016371 0 ustar 00root root 0000000 0000000 How to contribute to Deprecated Library
=======================================
Thank you for considering contributing to Deprecated!
Support questions
-----------------
Please, don't use the issue tracker for this. Use one of the following
resources for questions about your own code:
* Ask on `Stack Overflow`_. Search with Google first using:
``site:stackoverflow.com deprecated decorator {search term, exception message, etc.}``
.. _Stack Overflow: https://stackoverflow.com/search?q=python+deprecated+decorator
Reporting issues
----------------
- Describe what you expected to happen.
- If possible, include a `minimal, complete, and verifiable example`_ to help
us identify the issue. This also helps check that the issue is not with your
own code.
- Describe what actually happened. Include the full traceback if there was an
exception.
- List your Python, Deprecated versions. If possible, check if this
issue is already fixed in the repository.
.. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve
Submitting patches
------------------
- Include tests if your patch is supposed to solve a bug, and explain
clearly under which circumstances the bug happens. Make sure the test fails
without your patch.
- Try to follow `PEP8`_, but you may ignore the line length limit if following
it would make the code uglier.
First time setup
~~~~~~~~~~~~~~~~
- Download and install the `latest version of git`_.
- Configure git with your `username`_ and `email`_::
git config --global user.name 'your name'
git config --global user.email 'your email'
- Make sure you have a `GitHub account`_.
- Fork Deprecated to your GitHub account by clicking the `Fork`_ button.
- `Clone`_ your GitHub fork locally::
git clone https://github.com/{username}/deprecated.git
cd deprecated
- Add the main repository as a remote to update later::
git remote add upstream https://github.com/laurent-laporte-pro/deprecated.git
git fetch upstream
- Create a virtualenv::
python3 -m venv env
. env/bin/activate
# or "env\Scripts\activate" on Windows
- Install Deprecated in editable mode with development dependencies::
pip install -e ".[dev]"
.. _GitHub account: https://github.com/join
.. _latest version of git: https://git-scm.com/downloads
.. _username: https://help.github.com/articles/setting-your-username-in-git/
.. _email: https://help.github.com/articles/setting-your-commit-email-address-in-git/
.. _Fork: https://github.com/laurent-laporte-pro/deprecated#fork-destination-box
.. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork
Start coding
~~~~~~~~~~~~
- Create a branch to identify the issue you would like to work on (e.g.
``2287-dry-test-suite``)
- Using your favorite editor, make your changes, `committing as you go`_.
- Try to follow `PEP8`_, but you may ignore the line length limit if following
it would make the code uglier.
- Include tests that cover any code changes you make. Make sure the test fails
without your patch. `Running the tests`_.
- Push your commits to GitHub and `create a pull request`_.
- Celebrate 🎉
.. _committing as you go: http://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
.. _PEP8: https://pep8.org/
.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
Running the tests
~~~~~~~~~~~~~~~~~
Run the basic test suite with::
pytest tests/
This only runs the tests for the current environment. Whether this is relevant
depends on which part of Deprecated you're working on. Travis-CI will run the full
suite when you submit your pull request.
The full test suite takes a long time to run because it tests multiple
combinations of Python and dependencies. You need to have Python 2.7,
3.4, 3.5, 3.6, PyPy 2.7 and 3.6 installed to run all of the environments (notice
that Python **2.6** and **3.3** are no more supported). Then run::
tox
Running test coverage
~~~~~~~~~~~~~~~~~~~~~
Generating a report of lines that do not have test coverage can indicate
where to start contributing. Run ``pytest`` using ``coverage`` and generate a
report on the terminal and as an interactive HTML document::
pytest --cov-report term-missing --cov-report html --cov=deprecated tests/
# then open htmlcov/index.html
Read more about `coverage `_.
Running the full test suite with ``tox`` will combine the coverage reports
from all runs.
``make`` targets
~~~~~~~~~~~~~~~~
Deprecated provides a ``Makefile`` with various shortcuts. They will ensure that
all dependencies are installed.
- ``make test`` runs the basic test suite with ``pytest``
- ``make cov`` runs the basic test suite with ``coverage``
- ``make test-all`` runs the full test suite with ``tox``
Generating the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The documentation is automatically generated with ReadTheDocs for each git push on master.
You can also generate it manually using Sphinx.
To generate the HTML documentation, run::
sphinx-build -b html -d dist/docs/doctrees docs/source/ dist/docs/html/
To generate the epub v2 documentation, run::
sphinx-build -b epub -d dist/docs/doctrees docs/source/ dist/docs/epub/
deprecated-1.2.18/LICENSE.rst 0000664 0000000 0000000 00000002071 14745661623 0015535 0 ustar 00root root 0000000 0000000 The MIT License (MIT)
Copyright (c) 2017 Laurent LAPORTE
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. deprecated-1.2.18/MANIFEST.in 0000664 0000000 0000000 00000000423 14745661623 0015456 0 ustar 00root root 0000000 0000000 graft docs
graft deprecated
graft tests
graft .github
include .bumpversion.cfg
include .coveragerc
include .editorconfig
include *.rst
include *.spec
include *.yaml
include *.yml
include Makefile
include tox.ini
global-exclude *.py[cod] __pycache__ *.so *.dylib .DS_Store
deprecated-1.2.18/Makefile 0000664 0000000 0000000 00000001415 14745661623 0015362 0 ustar 00root root 0000000 0000000 .PHONY: all install-dev test coverage cov test-all tox release-minor release-patch upload-minor upload-patch clean-pyc
all: test
install-dev:
pip install -q -e .[dev]
test: clean-pyc install-dev
pytest tests/
coverage: clean-pyc install-dev
pytest --cov-report term-missing --cov-report html --cov=deprecated tests/
cov: coverage
test-all: install-dev
tox
tox: test-all
release-minor:
bumpversion minor
python setup.py release
release-patch:
bumpversion patch
python setup.py release
upload-minor: release-minor
python setup.py upload
git push origin --tags
upload-patch: release-patch
python setup.py upload
git push origin --tags
clean-pyc:
find . -name '*.pyc' -exec rm -f {} +
find . -name '*.pyo' -exec rm -f {} +
find . -name '*~' -exec rm -f {} +
deprecated-1.2.18/README.md 0000664 0000000 0000000 00000004614 14745661623 0015205 0 ustar 00root root 0000000 0000000 # Deprecated Decorator
Python ``@deprecated`` decorator to deprecate old python classes, functions or methods.
[](https://raw.githubusercontent.com/laurent-laporte-pro/deprecated/master/LICENSE.rst)
[](https://github.com/laurent-laporte-pro/deprecated/releases/latest)
[](https://pypi.org/project/Deprecated/)
[](https://github.com/laurent-laporte-pro/deprecated/actions/workflows/python-package.yml)
[](https://coveralls.io/github/laurent-laporte-pro/deprecated?branch=master)
[
](http://deprecated.readthedocs.io/en/latest/?badge=latest)
## Installation
```shell
pip install Deprecated
```
## Usage
To use this, decorate your deprecated function with **@deprecated** decorator:
```python
from deprecated import deprecated
@deprecated
def some_old_function(x, y):
return x + y
```
You can also decorate a class or a method:
```python
from deprecated import deprecated
class SomeClass(object):
@deprecated
def some_old_method(self, x, y):
return x + y
@deprecated
class SomeOldClass(object):
pass
```
You can give a "reason" message to help the developer to choose another function/class:
```python
from deprecated import deprecated
@deprecated(reason="use another function")
def some_old_function(x, y):
return x + y
```
## Authors
The authors of this library are:
[Marcos CARDOSO](https://github.com/vrcmarcos), and
[Laurent LAPORTE](https://github.com/laurent-laporte-pro).
The original code was made in [this StackOverflow post](https://stackoverflow.com/questions/2536307) by
[Leandro REGUEIRO](https://stackoverflow.com/users/1336250/leandro-regueiro),
[Patrizio BERTONI](https://stackoverflow.com/users/1315480/patrizio-bertoni), and
[Eric WIESER](https://stackoverflow.com/users/102441/eric).
deprecated-1.2.18/deprecated/ 0000775 0000000 0000000 00000000000 14745661623 0016021 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/deprecated/__init__.py 0000664 0000000 0000000 00000000537 14745661623 0020137 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*-
"""
Deprecated Library
==================
Python ``@deprecated`` decorator to deprecate old python classes, functions or methods.
"""
__version__ = "1.2.18"
__author__ = u"Laurent LAPORTE "
__date__ = "2025-01-27"
__credits__ = "(c) Laurent LAPORTE"
from deprecated.classic import deprecated
deprecated-1.2.18/deprecated/classic.py 0000664 0000000 0000000 00000024561 14745661623 0020024 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*-
"""
Classic deprecation warning
===========================
Classic ``@deprecated`` decorator to deprecate old python classes, functions or methods.
.. _The Warnings Filter: https://docs.python.org/3/library/warnings.html#the-warnings-filter
"""
import functools
import inspect
import platform
import warnings
import wrapt
try:
# If the C extension for wrapt was compiled and wrapt/_wrappers.pyd exists, then the
# stack level that should be passed to warnings.warn should be 2. However, if using
# a pure python wrapt, an extra stacklevel is required.
import wrapt._wrappers
_routine_stacklevel = 2
_class_stacklevel = 2
except ImportError:
_routine_stacklevel = 3
if platform.python_implementation() == "PyPy":
_class_stacklevel = 2
else:
_class_stacklevel = 3
string_types = (type(b''), type(u''))
class ClassicAdapter(wrapt.AdapterFactory):
"""
Classic adapter -- *for advanced usage only*
This adapter is used to get the deprecation message according to the wrapped object type:
class, function, standard method, static method, or class method.
This is the base class of the :class:`~deprecated.sphinx.SphinxAdapter` class
which is used to update the wrapped object docstring.
You can also inherit this class to change the deprecation message.
In the following example, we change the message into "The ... is deprecated.":
.. code-block:: python
import inspect
from deprecated.classic import ClassicAdapter
from deprecated.classic import deprecated
class MyClassicAdapter(ClassicAdapter):
def get_deprecated_msg(self, wrapped, instance):
if instance is None:
if inspect.isclass(wrapped):
fmt = "The class {name} is deprecated."
else:
fmt = "The function {name} is deprecated."
else:
if inspect.isclass(instance):
fmt = "The class method {name} is deprecated."
else:
fmt = "The method {name} is deprecated."
if self.reason:
fmt += " ({reason})"
if self.version:
fmt += " -- Deprecated since version {version}."
return fmt.format(name=wrapped.__name__,
reason=self.reason or "",
version=self.version or "")
Then, you can use your ``MyClassicAdapter`` class like this in your source code:
.. code-block:: python
@deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
def some_old_function(x, y):
return x + y
"""
def __init__(self, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0):
"""
Construct a wrapper adapter.
:type reason: str
:param reason:
Reason message which documents the deprecation in your library (can be omitted).
:type version: str
:param version:
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH".
:type action: Literal["default", "error", "ignore", "always", "module", "once"]
:param action:
A warning filter used to activate or not the deprecation warning.
Can be one of "error", "ignore", "always", "default", "module", or "once".
If ``None`` or empty, the global filtering mechanism is used.
See: `The Warnings Filter`_ in the Python documentation.
:type category: Type[Warning]
:param category:
The warning category to use for the deprecation warning.
By default, the category class is :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
:type extra_stacklevel: int
:param extra_stacklevel:
Number of additional stack levels to consider instrumentation rather than user code.
With the default value of 0, the warning refers to where the class was instantiated
or the function was called.
.. versionchanged:: 1.2.15
Add the *extra_stacklevel* parameter.
"""
self.reason = reason or ""
self.version = version or ""
self.action = action
self.category = category
self.extra_stacklevel = extra_stacklevel
super(ClassicAdapter, self).__init__()
def get_deprecated_msg(self, wrapped, instance):
"""
Get the deprecation warning message for the user.
:param wrapped: Wrapped class or function.
:param instance: The object to which the wrapped function was bound when it was called.
:return: The warning message.
"""
if instance is None:
if inspect.isclass(wrapped):
fmt = "Call to deprecated class {name}."
else:
fmt = "Call to deprecated function (or staticmethod) {name}."
else:
if inspect.isclass(instance):
fmt = "Call to deprecated class method {name}."
else:
fmt = "Call to deprecated method {name}."
if self.reason:
fmt += " ({reason})"
if self.version:
fmt += " -- Deprecated since version {version}."
return fmt.format(name=wrapped.__name__, reason=self.reason or "", version=self.version or "")
def __call__(self, wrapped):
"""
Decorate your class or function.
:param wrapped: Wrapped class or function.
:return: the decorated class or function.
.. versionchanged:: 1.2.4
Don't pass arguments to :meth:`object.__new__` (other than *cls*).
.. versionchanged:: 1.2.8
The warning filter is not set if the *action* parameter is ``None`` or empty.
"""
if inspect.isclass(wrapped):
old_new1 = wrapped.__new__
def wrapped_cls(cls, *args, **kwargs):
msg = self.get_deprecated_msg(wrapped, None)
stacklevel = _class_stacklevel + self.extra_stacklevel
if self.action:
with warnings.catch_warnings():
warnings.simplefilter(self.action, self.category)
warnings.warn(msg, category=self.category, stacklevel=stacklevel)
else:
warnings.warn(msg, category=self.category, stacklevel=stacklevel)
if old_new1 is object.__new__:
return old_new1(cls)
# actually, we don't know the real signature of *old_new1*
return old_new1(cls, *args, **kwargs)
wrapped.__new__ = staticmethod(wrapped_cls)
elif inspect.isroutine(wrapped):
@wrapt.decorator
def wrapper_function(wrapped_, instance_, args_, kwargs_):
msg = self.get_deprecated_msg(wrapped_, instance_)
stacklevel = _routine_stacklevel + self.extra_stacklevel
if self.action:
with warnings.catch_warnings():
warnings.simplefilter(self.action, self.category)
warnings.warn(msg, category=self.category, stacklevel=stacklevel)
else:
warnings.warn(msg, category=self.category, stacklevel=stacklevel)
return wrapped_(*args_, **kwargs_)
return wrapper_function(wrapped)
else:
raise TypeError(repr(type(wrapped)))
return wrapped
def deprecated(*args, **kwargs):
"""
This is a decorator which can be used to mark functions
as deprecated. It will result in a warning being emitted
when the function is used.
**Classic usage:**
To use this, decorate your deprecated function with **@deprecated** decorator:
.. code-block:: python
from deprecated import deprecated
@deprecated
def some_old_function(x, y):
return x + y
You can also decorate a class or a method:
.. code-block:: python
from deprecated import deprecated
class SomeClass(object):
@deprecated
def some_old_method(self, x, y):
return x + y
@deprecated
class SomeOldClass(object):
pass
You can give a *reason* message to help the developer to choose another function/class,
and a *version* number to specify the starting version number of the deprecation.
.. code-block:: python
from deprecated import deprecated
@deprecated(reason="use another function", version='1.2.0')
def some_old_function(x, y):
return x + y
The *category* keyword argument allow you to specify the deprecation warning class of your choice.
By default, :exc:`DeprecationWarning` is used, but you can choose :exc:`FutureWarning`,
:exc:`PendingDeprecationWarning` or a custom subclass.
.. code-block:: python
from deprecated import deprecated
@deprecated(category=PendingDeprecationWarning)
def some_old_function(x, y):
return x + y
The *action* keyword argument allow you to locally change the warning filtering.
*action* can be one of "error", "ignore", "always", "default", "module", or "once".
If ``None``, empty or missing, the global filtering mechanism is used.
See: `The Warnings Filter`_ in the Python documentation.
.. code-block:: python
from deprecated import deprecated
@deprecated(action="error")
def some_old_function(x, y):
return x + y
The *extra_stacklevel* keyword argument allows you to specify additional stack levels
to consider instrumentation rather than user code. With the default value of 0, the
warning refers to where the class was instantiated or the function was called.
"""
if args and isinstance(args[0], string_types):
kwargs['reason'] = args[0]
args = args[1:]
if args and not callable(args[0]):
raise TypeError(repr(type(args[0])))
if args:
adapter_cls = kwargs.pop('adapter_cls', ClassicAdapter)
adapter = adapter_cls(**kwargs)
wrapped = args[0]
return adapter(wrapped)
return functools.partial(deprecated, **kwargs)
deprecated-1.2.18/deprecated/sphinx.py 0000664 0000000 0000000 00000025545 14745661623 0017717 0 ustar 00root root 0000000 0000000 # coding: utf-8
"""
Sphinx directive integration
============================
We usually need to document the life-cycle of functions and classes:
when they are created, modified or deprecated.
To do that, `Sphinx `_ has a set
of `Paragraph-level markups `_:
- ``versionadded``: to document the version of the project which added the described feature to the library,
- ``versionchanged``: to document changes of a feature,
- ``deprecated``: to document a deprecated feature.
The purpose of this module is to defined decorators which adds this Sphinx directives
to the docstring of your function and classes.
Of course, the ``@deprecated`` decorator will emit a deprecation warning
when the function/method is called or the class is constructed.
"""
import re
import textwrap
from deprecated.classic import ClassicAdapter
from deprecated.classic import deprecated as _classic_deprecated
class SphinxAdapter(ClassicAdapter):
"""
Sphinx adapter -- *for advanced usage only*
This adapter override the :class:`~deprecated.classic.ClassicAdapter`
in order to add the Sphinx directives to the end of the function/class docstring.
Such a directive is a `Paragraph-level markup `_
- The directive can be one of "versionadded", "versionchanged" or "deprecated".
- The version number is added if provided.
- The reason message is obviously added in the directive block if not empty.
"""
def __init__(
self,
directive,
reason="",
version="",
action=None,
category=DeprecationWarning,
extra_stacklevel=0,
line_length=70,
):
"""
Construct a wrapper adapter.
:type directive: str
:param directive:
Sphinx directive: can be one of "versionadded", "versionchanged" or "deprecated".
:type reason: str
:param reason:
Reason message which documents the deprecation in your library (can be omitted).
:type version: str
:param version:
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH".
:type action: Literal["default", "error", "ignore", "always", "module", "once"]
:param action:
A warning filter used to activate or not the deprecation warning.
Can be one of "error", "ignore", "always", "default", "module", or "once".
If ``None`` or empty, the global filtering mechanism is used.
See: `The Warnings Filter`_ in the Python documentation.
:type category: Type[Warning]
:param category:
The warning category to use for the deprecation warning.
By default, the category class is :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
:type extra_stacklevel: int
:param extra_stacklevel:
Number of additional stack levels to consider instrumentation rather than user code.
With the default value of 0, the warning refers to where the class was instantiated
or the function was called.
:type line_length: int
:param line_length:
Max line length of the directive text. If non nul, a long text is wrapped in several lines.
.. versionchanged:: 1.2.15
Add the *extra_stacklevel* parameter.
"""
if not version:
# https://github.com/laurent-laporte-pro/deprecated/issues/40
raise ValueError("'version' argument is required in Sphinx directives")
self.directive = directive
self.line_length = line_length
super(SphinxAdapter, self).__init__(
reason=reason, version=version, action=action, category=category, extra_stacklevel=extra_stacklevel
)
def __call__(self, wrapped):
"""
Add the Sphinx directive to your class or function.
:param wrapped: Wrapped class or function.
:return: the decorated class or function.
"""
# -- build the directive division
fmt = ".. {directive}:: {version}" if self.version else ".. {directive}::"
div_lines = [fmt.format(directive=self.directive, version=self.version)]
width = self.line_length - 3 if self.line_length > 3 else 2**16
reason = textwrap.dedent(self.reason).strip()
for paragraph in reason.splitlines():
if paragraph:
div_lines.extend(
textwrap.fill(
paragraph,
width=width,
initial_indent=" ",
subsequent_indent=" ",
).splitlines()
)
else:
div_lines.append("")
# -- get the docstring, normalize the trailing newlines
# keep a consistent behaviour if the docstring starts with newline or directly on the first one
docstring = wrapped.__doc__ or ""
lines = docstring.splitlines(True) or [""]
docstring = textwrap.dedent("".join(lines[1:])) if len(lines) > 1 else ""
docstring = lines[0] + docstring
if docstring:
# An empty line must separate the original docstring and the directive.
docstring = re.sub(r"\n+$", "", docstring, flags=re.DOTALL) + "\n\n"
else:
# Avoid "Explicit markup ends without a blank line" when the decorated function has no docstring
docstring = "\n"
# -- append the directive division to the docstring
docstring += "".join("{}\n".format(line) for line in div_lines)
wrapped.__doc__ = docstring
if self.directive in {"versionadded", "versionchanged"}:
return wrapped
return super(SphinxAdapter, self).__call__(wrapped)
def get_deprecated_msg(self, wrapped, instance):
"""
Get the deprecation warning message (without Sphinx cross-referencing syntax) for the user.
:param wrapped: Wrapped class or function.
:param instance: The object to which the wrapped function was bound when it was called.
:return: The warning message.
.. versionadded:: 1.2.12
Strip Sphinx cross-referencing syntax from warning message.
"""
msg = super(SphinxAdapter, self).get_deprecated_msg(wrapped, instance)
# Strip Sphinx cross-reference syntax (like ":function:", ":py:func:" and ":py:meth:")
# Possible values are ":role:`foo`", ":domain:role:`foo`"
# where ``role`` and ``domain`` should match "[a-zA-Z]+"
msg = re.sub(r"(?: : [a-zA-Z]+ )? : [a-zA-Z]+ : (`[^`]*`)", r"\1", msg, flags=re.X)
return msg
def versionadded(reason="", version="", line_length=70):
"""
This decorator can be used to insert a "versionadded" directive
in your function/class docstring in order to document the
version of the project which adds this new functionality in your library.
:param str reason:
Reason message which documents the addition in your library (can be omitted).
:param str version:
Version of your project which adds this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH", and,
in the case of a new functionality, the "PATCH" component should be "0".
:type line_length: int
:param line_length:
Max line length of the directive text. If non nul, a long text is wrapped in several lines.
:return: the decorated function.
"""
adapter = SphinxAdapter(
'versionadded',
reason=reason,
version=version,
line_length=line_length,
)
return adapter
def versionchanged(reason="", version="", line_length=70):
"""
This decorator can be used to insert a "versionchanged" directive
in your function/class docstring in order to document the
version of the project which modifies this functionality in your library.
:param str reason:
Reason message which documents the modification in your library (can be omitted).
:param str version:
Version of your project which modifies this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH".
:type line_length: int
:param line_length:
Max line length of the directive text. If non nul, a long text is wrapped in several lines.
:return: the decorated function.
"""
adapter = SphinxAdapter(
'versionchanged',
reason=reason,
version=version,
line_length=line_length,
)
return adapter
def deprecated(reason="", version="", line_length=70, **kwargs):
"""
This decorator can be used to insert a "deprecated" directive
in your function/class docstring in order to document the
version of the project which deprecates this functionality in your library.
:param str reason:
Reason message which documents the deprecation in your library (can be omitted).
:param str version:
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH".
:type line_length: int
:param line_length:
Max line length of the directive text. If non nul, a long text is wrapped in several lines.
Keyword arguments can be:
- "action":
A warning filter used to activate or not the deprecation warning.
Can be one of "error", "ignore", "always", "default", "module", or "once".
If ``None``, empty or missing, the global filtering mechanism is used.
- "category":
The warning category to use for the deprecation warning.
By default, the category class is :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
- "extra_stacklevel":
Number of additional stack levels to consider instrumentation rather than user code.
With the default value of 0, the warning refers to where the class was instantiated
or the function was called.
:return: a decorator used to deprecate a function.
.. versionchanged:: 1.2.13
Change the signature of the decorator to reflect the valid use cases.
.. versionchanged:: 1.2.15
Add the *extra_stacklevel* parameter.
"""
directive = kwargs.pop('directive', 'deprecated')
adapter_cls = kwargs.pop('adapter_cls', SphinxAdapter)
kwargs["reason"] = reason
kwargs["version"] = version
kwargs["line_length"] = line_length
return _classic_deprecated(directive=directive, adapter_cls=adapter_cls, **kwargs)
deprecated-1.2.18/docs/ 0000775 0000000 0000000 00000000000 14745661623 0014651 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/docs/blurb.rst 0000664 0000000 0000000 00000000773 14745661623 0016520 0 ustar 00root root 0000000 0000000 If you need to mark a function, a class or a method as deprecated, you can use the @deprecated decorator.
This documentation explains how to install and use the Deprecated Library.
It includes a detailed tutorial and simple use cases.
You will also have all the keys to contribute to the source code development.
Why should you pay for this documentation? This a way to donate to the Deprecated Library project.
Your gratitude and financial help will be motivating to continue the project’s development.
deprecated-1.2.18/docs/cover/ 0000775 0000000 0000000 00000000000 14745661623 0015767 5 ustar 00root root 0000000 0000000 deprecated-1.2.18/docs/cover/paper_10.jpeg 0000664 0000000 0000000 00010647637 14745661623 0020275 0 ustar 00root root 0000000 0000000 JFIF H H #rExif II* z ( 2 i $# Canon Canon EOS DIGITAL REBEL XS H H 2017:08:22 23:42:25 : B " ' 0221 J ^
r z
| \ ! 06 06 06 0100 0
# " " <