Metadata-Version: 2.1
Name: regret
Version: 0.42.0
Summary: You made a thing, but now you wish it'd go away... Deprecations, a love story.
Project-URL: documentation, https://regret.readthedocs.io/
Project-URL: funding, https://github.com/sponsors/Julian
Project-URL: homepage, https://github.com/Julian/regret
Project-URL: issues, https://github.com/Julian/regret/issues/
Project-URL: source, https://github.com/Julian/regret
Author: Julian Berman
Author-email: Julian+regret@GrayVines.com
License: MIT
Keywords: deprecation,deprecations,maintenance,regret,tooling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.7
Requires-Dist: attrs
Description-Content-Type: text/x-rst

======
regret
======

|PyPI| |Pythons| |CI| |Codecov| |ReadTheDocs|

.. |PyPI| image:: https://img.shields.io/pypi/v/regret.svg
  :alt: PyPI version
  :target: https://pypi.org/project/regret/

.. |Pythons| image:: https://img.shields.io/pypi/pyversions/regret.svg
  :alt: Supported Python versions
  :target: https://pypi.org/project/regret/

.. |CI| image:: https://github.com/Julian/regret/workflows/CI/badge.svg
  :alt: Build status
  :target: https://github.com/Julian/regret/actions?query=workflow%3ACI

.. |Codecov| image:: https://codecov.io/gh/Julian/regret/branch/master/graph/badge.svg
  :alt: Codecov Code coverage
  :target: https://codecov.io/gh/Julian/regret

.. |ReadTheDocs| image:: https://readthedocs.org/projects/regret/badge/?version=stable&style=flat
  :alt: ReadTheDocs status
  :target: https://regret.readthedocs.io/en/stable/

``regret`` is a library for deprecating functionality in Python
libraries and applications.

Its documentation lives on `Read the Docs
<https://regret.readthedocs.io/en/stable/>`_.


Deprecations
------------

``regret`` can deprecate:

    - [x] callables
        - [x] functions
        - [x] classes
            - [ ] subclassable classes
    - [ ] attributes
        - [ ] of modules
        - [ ] of classes
        - [ ] of instances
    - [ ] descriptors
        - [ ] classmethod
    - [ ] modules
        - [ ] current module
        - [ ] other module
    - [ ] parameters to callables
        - [x] previously required parameters that will be removed
        - [x] optional parameters that are now required
        - [ ] deprecated values for parameters
        - [ ] type changes for parameters
        - [ ] mutual exclusion
    - [ ] interfaces
        - [ ] PEP 544 protocols
        - [ ] ``zope.interface``\s
    - [x] inheritability of a class


Design Goals
------------

``regret`` is meant to cover all of the deprecations an author may encounter.

It is intended to:

    * be versioning system agnostic (i.e. `SemVer
      <https://semver.org/>`_, `CalVer <https://calver.org/>`_, `HipsTer
      <https://en.wikipedia.org/wiki/Hipster_(contemporary_subculture)>`_,
      etc.), because deprecations originate from a version, a point in
      time, or both.

    * be documentation system aware (i.e. `Sphinx
      <https://www.sphinx-doc.org>`_, `epydoc
      <https://en.wikipedia.org/wiki/Epydoc>`_, `Plaintext
      <https://www.google.com/search?q=use+sphinx>`_, etc.), because
      deprecations need communication.

    * be itself fully tested, because deprecations must not break the
      code they deprecate

    * support removal date indication, and likely "policies" which
      automate choosing default removal dates, because deprecations
      ultimately intend some ultimate change

    * make "clean code" trivially easy to deprecate, and make complex
      code *possible* to deprecate, because the deprecation process is
      fraught with edge cases and unforeseen necessity.

    * minimize the amount of deprecation-related code required for
      authors, since deprecations are boring, and we all want to focus on
      developing our libraries instead.

In particular, as a lofty first milestone, it is intended to cover all
of the specific deprecations required for these `jsonschema issues
<https://github.com/Julian/jsonschema/issues?utf8=%E2%9C%93&q=label%3A%22Pending+Deprecation%22>`_,
and with luck, to subsume all the functionality present in
`twisted.python.deprecate <https://twistedmatrix.com/documents/current/api/twisted.python.deprecate.html>`_.
