[Python-modules-commits] [python-attrs] 01/15: Import python-attrs_17.2.0.orig.tar.gz
Tristan Seligmann
mithrandi at moszumanska.debian.org
Fri Jun 30 02:27:34 UTC 2017
This is an automated email from the git hooks/post-receive script.
mithrandi pushed a commit to branch master
in repository python-attrs.
commit 5f47c131690f268c584cb69b4f88d6b50986b57e
Author: Tristan Seligmann <mithrandi at mithrandi.net>
Date: Fri Jun 30 03:28:42 2017 +0200
Import python-attrs_17.2.0.orig.tar.gz
---
.travis.yml | 10 +-
AUTHORS.rst | 2 +-
CHANGELOG.rst | 178 ++++++++++++++++++----
CONTRIBUTING.rst | 103 ++++++++++---
MANIFEST.in | 14 +-
PULL_REQUEST_TEMPLATE.md | 12 ++
README.rst | 92 +++++++-----
conftest.py | 5 +-
dev-requirements.txt | 1 +
docs-requirements.txt | 3 +
docs/_static/attrs_logo.png | Bin 0 -> 7639 bytes
docs/api.rst | 108 +++++++++++--
docs/conf.py | 189 +++--------------------
docs/docutils.conf | 3 +
docs/examples.rst | 146 +++++++++++-------
docs/extending.rst | 4 +-
docs/how-does-it-work.rst | 2 +-
docs/index.rst | 6 +-
docs/license.rst | 4 +-
docs/why.rst | 81 +++++-----
src/attr/__init__.py | 12 +-
src/attr/_funcs.py | 34 +++++
src/attr/_make.py | 358 ++++++++++++++++++++++++++++++++++----------
src/attr/converters.py | 24 +++
src/attr/exceptions.py | 9 ++
src/attr/validators.py | 84 +++++++++--
tests/test_converters.py | 36 +++++
tests/test_dark_magic.py | 68 ++++++++-
tests/test_dunders.py | 77 +++++++++-
tests/test_funcs.py | 143 ++++++++++++++++--
tests/test_make.py | 189 ++++++++++++++++++++---
tests/test_slots.py | 14 +-
tests/test_validators.py | 134 +++++++++++++++--
tests/utils.py | 41 ++++-
tox.ini | 20 ++-
35 files changed, 1644 insertions(+), 562 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index 088f7dd..d3f21dc 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -14,17 +14,19 @@ matrix:
env: TOXENV=py34
- python: "3.5"
env: TOXENV=py35
+ - python: "3.6"
+ env: TOXENV=py36
- python: "pypy"
env: TOXENV=pypy
# Meta
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=flake8
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=manifest
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=docs
- - python: "3.5"
+ - python: "3.6"
env: TOXENV=readme
diff --git a/AUTHORS.rst b/AUTHORS.rst
index 79dba74..73eae21 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -5,7 +5,7 @@ Credits
The development is kindly supported by `Variomedia AG <https://www.variomedia.de/>`_.
-A full list of contributors can be found in `GitHub's overview <https://github.com/hynek/attrs/graphs/contributors>`_.
+A full list of contributors can be found in `GitHub's overview <https://github.com/python-attrs/attrs/graphs/contributors>`_.
It’s the spiritual successor of `characteristic <https://characteristic.readthedocs.io/>`_ and aspires to fix some of it clunkiness and unfortunate decisions.
Both were inspired by Twisted’s `FancyEqMixin <https://twistedmatrix.com/documents/current/api/twisted.python.util.FancyEqMixin.html>`_ but both are implemented using class decorators because `sub-classing is bad for you <https://www.youtube.com/watch?v=3MNVP9-hglc>`_, m’kay?
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 364c612..fc9148a 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -5,6 +5,120 @@ Versions follow `CalVer <http://calver.org>`_ with a strict backwards compatibil
The third digit is only for regressions.
+17.2.0 (2017-05-24)
+-------------------
+
+
+Backward-incompatible changes:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*none*
+
+
+Deprecations:
+^^^^^^^^^^^^^
+
+*none*
+
+
+Changes:
+^^^^^^^^
+
+- Validators are hashable again.
+ Note that validators may become frozen in the future, pending availability of no-overhead frozen classes.
+ `#192 <https://github.com/python-attrs/attrs/issues/192>`_
+
+
+----
+
+
+17.1.0 (2017-05-16)
+-------------------
+
+To encourage more participation, the project has also been moved into a `dedicated GitHub organization <https://github.com/python-attrs/>`_ and everyone is most welcome to join!
+
+``attrs`` also has a logo now!
+
+.. image:: http://www.attrs.org/en/latest/_static/attrs_logo.png
+ :alt: attrs logo
+
+
+Backward-incompatible changes:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``attrs`` will set the ``__hash__()`` method to ``None`` by default now.
+ The way hashes were handled before was in conflict with `Python's specification <https://docs.python.org/3/reference/datamodel.html#object.__hash__>`_.
+ This *may* break some software although this breakage is most likely just surfacing of latent bugs.
+ You can always make ``attrs`` create the ``__hash__()`` method using ``@attr.s(hash=True)``.
+ See `#136`_ for the rationale of this change.
+
+ .. warning::
+
+ Please *do not* upgrade blindly and *do* test your software!
+ *Especially* if you use instances as dict keys or put them into sets!
+
+- Correspondingly, ``attr.ib``'s ``hash`` argument is ``None`` by default too and mirrors the ``cmp`` argument as it should.
+
+
+Deprecations:
+^^^^^^^^^^^^^
+
+- ``attr.assoc()`` is now deprecated in favor of ``attr.evolve()`` and will stop working in 2018.
+
+
+Changes:
+^^^^^^^^
+
+- Fix default hashing behavior.
+ Now *hash* mirrors the value of *cmp* and classes are unhashable by default.
+ `#136`_
+ `#142 <https://github.com/python-attrs/attrs/issues/142>`_
+- Added ``attr.evolve()`` that, given an instance of an ``attrs`` class and field changes as keyword arguments, will instantiate a copy of the given instance with the changes applied.
+ ``evolve()`` replaces ``assoc()``, which is now deprecated.
+ ``evolve()`` is significantly faster than ``assoc()``, and requires the class have an initializer that can take the field values as keyword arguments (like ``attrs`` itself can generate).
+ `#116 <https://github.com/python-attrs/attrs/issues/116>`_
+ `#124 <https://github.com/python-attrs/attrs/pull/124>`_
+ `#135 <https://github.com/python-attrs/attrs/pull/135>`_
+- ``FrozenInstanceError`` is now raised when trying to delete an attribute from a frozen class.
+ `#118 <https://github.com/python-attrs/attrs/pull/118>`_
+- Frozen-ness of classes is now inherited.
+ `#128 <https://github.com/python-attrs/attrs/pull/128>`_
+- ``__attrs_post_init__()`` is now run if validation is disabled.
+ `#130 <https://github.com/python-attrs/attrs/pull/130>`_
+- Added ``attr.validators.in_(options)`` that, given the allowed `options`, checks whether the attribute value is in it.
+ This can be used to check constants, enums, mappings, etc.
+ `#181 <https://github.com/python-attrs/attrs/pull/181>`_
+- Added ``attr.validators.and_()`` that composes multiple validators into one.
+ `#161 <https://github.com/python-attrs/attrs/issues/161>`_
+- For convenience, the ``validator`` argument of ``@attr.s`` now can take a ``list`` of validators that are wrapped using ``and_()``.
+ `#138 <https://github.com/python-attrs/attrs/issues/138>`_
+- Accordingly, ``attr.validators.optional()`` now can take a ``list`` of validators too.
+ `#161 <https://github.com/python-attrs/attrs/issues/161>`_
+- Validators can now be defined conveniently inline by using the attribute as a decorator.
+ Check out the `examples <http://www.attrs.org/en/stable/examples.html#validators>`_ to see it in action!
+ `#143 <https://github.com/python-attrs/attrs/issues/143>`_
+- ``attr.Factory()`` now has a ``takes_self`` argument that makes the initializer to pass the partially initialized instance into the factory.
+ In other words you can define attribute defaults based on other attributes.
+ `#165`_
+ `#189 <https://github.com/python-attrs/attrs/issues/189>`_
+- Default factories can now also be defined inline using decorators.
+ They are *always* passed the partially initialized instance.
+ `#165`_
+- Conversion can now be made optional using ``attr.converters.optional()``.
+ `#105 <https://github.com/python-attrs/attrs/issues/105>`_
+ `#173 <https://github.com/python-attrs/attrs/pull/173>`_
+- ``attr.make_class()`` now accepts the keyword argument ``bases`` which allows for subclassing.
+ `#152 <https://github.com/python-attrs/attrs/pull/152>`_
+- Metaclasses are now preserved with ``slots=True``.
+ `#155 <https://github.com/python-attrs/attrs/pull/155>`_
+
+.. _`#136`: https://github.com/python-attrs/attrs/issues/136
+.. _`#165`: https://github.com/python-attrs/attrs/issues/165
+
+
+----
+
+
16.3.0 (2016-11-24)
-------------------
@@ -12,16 +126,16 @@ Changes:
^^^^^^^^
- Attributes now can have user-defined metadata which greatly improves ``attrs``'s extensibility.
- `#96 <https://github.com/hynek/attrs/pull/96>`_
-- Allow for a ``__attrs_post_init__`` method that -- if defined -- will get called at the end of the ``attrs``-generated ``__init__`` method.
- `#111 <https://github.com/hynek/attrs/pull/111>`_
-- Add ``@attr.s(str=True)`` that will optionally create a ``__str__`` method that is identical to ``__repr__``.
- This is mainly useful with ``Exception``\ s and other classes that rely on a useful ``__str__`` implementation but overwrite the default one through a poor own one.
- Default Python class behavior is to use ``__repr__`` as ``__str__`` anyways.
+ `#96 <https://github.com/python-attrs/attrs/pull/96>`_
+- Allow for a ``__attrs_post_init__()`` method that -- if defined -- will get called at the end of the ``attrs``-generated ``__init__()`` method.
+ `#111 <https://github.com/python-attrs/attrs/pull/111>`_
+- Added ``@attr.s(str=True)`` that will optionally create a ``__str__()`` method that is identical to ``__repr__()``.
+ This is mainly useful with ``Exception``\ s and other classes that rely on a useful ``__str__()`` implementation but overwrite the default one through a poor own one.
+ Default Python class behavior is to use ``__repr__()`` as ``__str__()`` anyways.
If you tried using ``attrs`` with ``Exception``\ s and were puzzled by the tracebacks: this option is for you.
-- Don't overwrite ``__name__`` with ``__qualname__`` for ``attr.s(slots=True)`` classes.
- `#99 <https://github.com/hynek/attrs/issues/99>`_
+- ``__name__`` is not overwritten with ``__qualname__`` for ``attr.s(slots=True)`` classes anymore.
+ `#99 <https://github.com/python-attrs/attrs/issues/99>`_
----
@@ -33,20 +147,20 @@ Changes:
Changes:
^^^^^^^^
-- Add ``attr.astuple()`` that -- similarly to ``attr.asdict()`` -- returns the instance as a tuple.
- `#77 <https://github.com/hynek/attrs/issues/77>`_
+- Added ``attr.astuple()`` that -- similarly to ``attr.asdict()`` -- returns the instance as a tuple.
+ `#77 <https://github.com/python-attrs/attrs/issues/77>`_
- Converts now work with frozen classes.
- `#76 <https://github.com/hynek/attrs/issues/76>`_
+ `#76 <https://github.com/python-attrs/attrs/issues/76>`_
- Instantiation of ``attrs`` classes with converters is now significantly faster.
- `#80 <https://github.com/hynek/attrs/pull/80>`_
+ `#80 <https://github.com/python-attrs/attrs/pull/80>`_
- Pickling now works with ``__slots__`` classes.
- `#81 <https://github.com/hynek/attrs/issues/81>`_
+ `#81 <https://github.com/python-attrs/attrs/issues/81>`_
- ``attr.assoc()`` now works with ``__slots__`` classes.
- `#84 <https://github.com/hynek/attrs/issues/84>`_
+ `#84 <https://github.com/python-attrs/attrs/issues/84>`_
- The tuple returned by ``attr.fields()`` now also allows to access the ``Attribute`` instances by name.
Yes, we've subclassed ``tuple`` so you don't have to!
Therefore ``attr.fields(C).x`` is equivalent to the deprecated ``C.x`` and works with ``__slots__`` classes.
- `#88 <https://github.com/hynek/attrs/issues/88>`_
+ `#88 <https://github.com/python-attrs/attrs/issues/88>`_
----
@@ -81,16 +195,16 @@ Changes:
^^^^^^^^
- ``attr.asdict()``\ 's ``dict_factory`` arguments is now propagated on recursion.
- `#45 <https://github.com/hynek/attrs/issues/45>`_
+ `#45 <https://github.com/python-attrs/attrs/issues/45>`_
- ``attr.asdict()``, ``attr.has()`` and ``attr.fields()`` are significantly faster.
- `#48 <https://github.com/hynek/attrs/issues/48>`_
- `#51 <https://github.com/hynek/attrs/issues/51>`_
+ `#48 <https://github.com/python-attrs/attrs/issues/48>`_
+ `#51 <https://github.com/python-attrs/attrs/issues/51>`_
- Add ``attr.attrs`` and ``attr.attrib`` as a more consistent aliases for ``attr.s`` and ``attr.ib``.
- Add ``frozen`` option to ``attr.s`` that will make instances best-effort immutable.
- `#60 <https://github.com/hynek/attrs/issues/60>`_
+ `#60 <https://github.com/python-attrs/attrs/issues/60>`_
- ``attr.asdict()`` now takes ``retain_collection_types`` as an argument.
If ``True``, it does not convert attributes of type ``tuple`` or ``set`` to ``list``.
- `#69 <https://github.com/hynek/attrs/issues/69>`_
+ `#69 <https://github.com/python-attrs/attrs/issues/69>`_
----
@@ -115,12 +229,12 @@ Changes:
- ``__slots__`` have arrived!
Classes now can automatically be `slots <https://docs.python.org/3.5/reference/datamodel.html#slots>`_-style (and save your precious memory) just by passing ``slots=True``.
- `#35 <https://github.com/hynek/attrs/issues/35>`_
+ `#35 <https://github.com/python-attrs/attrs/issues/35>`_
- Allow the case of initializing attributes that are set to ``init=False``.
This allows for clean initializer parameter lists while being able to initialize attributes to default values.
- `#32 <https://github.com/hynek/attrs/issues/32>`_
+ `#32 <https://github.com/python-attrs/attrs/issues/32>`_
- ``attr.asdict()`` can now produce arbitrary mappings instead of Python ``dict``\ s when provided with a ``dict_factory`` argument.
- `#40 <https://github.com/hynek/attrs/issues/40>`_
+ `#40 <https://github.com/python-attrs/attrs/issues/40>`_
- Multiple performance improvements.
@@ -133,11 +247,11 @@ Changes:
Changes:
^^^^^^^^
-- Add a ``convert`` argument to ``attr.ib``, which allows specifying a function to run on arguments.
+- Added a ``convert`` argument to ``attr.ib``, which allows specifying a function to run on arguments.
This allows for simple type conversions, e.g. with ``attr.ib(convert=int)``.
- `#26 <https://github.com/hynek/attrs/issues/26>`_
+ `#26 <https://github.com/python-attrs/attrs/issues/26>`_
- Speed up object creation when attribute validators are used.
- `#28 <https://github.com/hynek/attrs/issues/28>`_
+ `#28 <https://github.com/python-attrs/attrs/issues/28>`_
----
@@ -149,12 +263,12 @@ Changes:
Changes:
^^^^^^^^
-- Add ``attr.validators.optional`` that wraps other validators allowing attributes to be ``None``.
- `#16 <https://github.com/hynek/attrs/issues/16>`_
-- Fix multi-level inheritance.
- `#24 <https://github.com/hynek/attrs/issues/24>`_
-- Fix ``__repr__`` to work for non-redecorated subclasses.
- `#20 <https://github.com/hynek/attrs/issues/20>`_
+- Added ``attr.validators.optional()`` that wraps other validators allowing attributes to be ``None``.
+ `#16 <https://github.com/python-attrs/attrs/issues/16>`_
+- Multi-level inheritance now works.
+ `#24 <https://github.com/python-attrs/attrs/issues/24>`_
+- ``__repr__()`` now works with non-redecorated subclasses.
+ `#20 <https://github.com/python-attrs/attrs/issues/20>`_
----
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 7086b12..fa82ca2 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -4,7 +4,8 @@ How To Contribute
First off, thank you for considering contributing to ``attrs``!
It's people like *you* who make it is such a great tool for everyone.
-Here are a few guidelines to get you started (but don't be afraid to open half-finished PRs and ask questions if something is unclear!):
+This document is mainly to help you to get started by codifying tribal knowledge and expectations and make it more accessible to everyone.
+But don't be afraid to open half-finished PRs and ask questions if something is unclear!
Workflow
@@ -32,7 +33,7 @@ Code
def func(x):
"""
- Does something.
+ Do something.
:param str x: A very important parameter.
@@ -71,23 +72,85 @@ Documentation
This is a sentence.
This is another sentence.
+- If you start a new section, add two blank lines before and one blank line after the header except if two headers follow immediately after each other:
+
+ .. code-block:: rst
+
+ Last line of previous section.
+
+
+ Header of New Top Section
+ -------------------------
+
+ Header of New Section
+ ^^^^^^^^^^^^^^^^^^^^^
+
+ First line of new section.
- If you add a new feature, demonstrate its awesomeness in the `examples page`_!
- If your change is noteworthy, add an entry to the changelog_.
- Use present tense, `semantic newlines`_, and add a link to your pull request:
+ Use `semantic newlines`_, and add a link to your pull request:
.. code-block:: rst
- - Add awesome new feature.
+ - Added ``attr.validators.func()``.
The feature really *is* awesome.
- [`#1 <https://github.com/hynek/attrs/pull/1>`_]
- - Fix nasty bug.
+ [`#1 <https://github.com/python-attrs/attrs/pull/1>`_]
+ - ``attr.func()`` now doesn't crash the Large Hadron Collider anymore.
The bug really *was* nasty.
- [`#2 <https://github.com/hynek/attrs/pull/2>`_]
+ [`#2 <https://github.com/python-attrs/attrs/pull/2>`_]
-****
-Again, this list is mainly to help you to get started by codifying tribal knowledge and expectations.
-If something is unclear, feel free to ask for help!
+Local Development Environment
+-----------------------------
+
+You can (and should) run our test suite using tox_ however you’ll probably want a more traditional environment too.
+We highly recommend to develop using the latest Python 3 release because ``attrs`` tries to take advantage of modern features whenever possible.
+
+First create a `virtual environment <https://virtualenv.pypa.io/>`_.
+It’s out of scope for this document to list all the ways to manage virtual environments in Python but if you don’t have already a pet way, take some time to look at tools like `pew <https://github.com/berdario/pew>`_, `virtualfish <http://virtualfish.readthedocs.io/>`_, and `virtualenvwrapper <http://virtualenvwrapper.readthedocs.io/>`_.
+
+Next get an up to date checkout of the ``attrs`` repository:
+
+.. code-block:: bash
+
+ git checkout git at github.com:python-attrs/attrs.git
+
+Change into the newly created directory and **after activating your virtual environment** install an editable version of ``attrs``:
+
+.. code-block:: bash
+
+ cd attrs
+ pip install -e .
+
+If you run the virtual environment’s Python and try to ``import attr`` it should work!
+
+To run the test suite, you'll need our development dependencies which can be installed using
+
+.. code-block:: bash
+
+ pip install -r dev-requirements.txt
+
+At this point
+
+.. code-block:: bash
+
+ python -m pytest
+
+should work and pass!
+
+
+Governance
+----------
+
+``attrs`` is maintained by `team of volunteers`_ that is always open for new members that share our vision of a fast, lean, and magic-free library that empowers programmers to write better code with less effort.
+If you'd like to join, just get a pull request merged and ask to be added in the very same pull request!
+
+**The simple rule is that everyone is welcome to review/merge pull requests of others but nobody is allowed to merge their own code.**
+
+`Hynek Schlawack`_ acts reluctantly as the BDFL_ and has the final say over design decisions.
+
+
+****
Please note that this project is released with a Contributor `Code of Conduct`_.
By participating in this project you agree to abide by its terms.
@@ -100,13 +163,15 @@ Thank you for considering contributing to ``attrs``!
.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
.. _`PEP 257`: https://www.python.org/dev/peps/pep-0257/
.. _`good test docstrings`: https://jml.io/pages/test-docstrings.html
-.. _`Code of Conduct`: https://github.com/hynek/attrs/blob/master/CODE_OF_CONDUCT.rst
-.. _changelog: https://github.com/hynek/attrs/blob/master/CHANGELOG.rst
-.. _`backward compatibility`: https://attrs.readthedocs.io/en/latest/backward-compatibility.html
-.. _`tox`: https://testrun.org/tox/
-.. _pyenv: https://github.com/yyuu/pyenv
-.. _reStructuredText: http://sphinx-doc.org/rest.html
+.. _`Code of Conduct`: https://github.com/python-attrs/attrs/blob/master/CODE_OF_CONDUCT.rst
+.. _changelog: https://github.com/python-attrs/attrs/blob/master/CHANGELOG.rst
+.. _`backward compatibility`: http://www.attrs.org/en/latest/backward-compatibility.html
+.. _tox: https://tox.readthedocs.io/
+.. _pyenv: https://github.com/pyenv/pyenv
+.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
.. _semantic newlines: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
-.. _examples page: https://github.com/hynek/attrs/blob/master/docs/examples.rst
-.. _Hypothesis: https://hypothesis.readthedocs.org
-.. _CI: https://travis-ci.org/hynek/attrs/
+.. _examples page: https://github.com/python-attrs/attrs/blob/master/docs/examples.rst
+.. _Hypothesis: https://hypothesis.readthedocs.io/
+.. _CI: https://travis-ci.org/python-attrs/attrs/
+.. _`team of volunteers`: https://github.com/python-attrs
+.. _BDFL: https://en.wikipedia.org/wiki/Benevolent_dictator_for_life
diff --git a/MANIFEST.in b/MANIFEST.in
index 483a3a3..c7af0b0 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,5 +1,15 @@
-include *.rst *.txt LICENSE tox.ini .travis.yml docs/Makefile .coveragerc conftest.py
+include LICENSE *.rst
+
+# Don't package GitHub-specific files.
+exclude *.md .travis.yml
+
+# Tests
+include tox.ini .coveragerc conftest.py dev-requirements.txt docs-requirements.txt
recursive-include tests *.py
-recursive-include docs *.rst
+
+# Documentation
+include docs/Makefile docs/docutils.conf
+recursive-include docs *.png
recursive-include docs *.py
+recursive-include docs *.rst
prune docs/_build
diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..2a9d712
--- /dev/null
+++ b/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,12 @@
+# Pull Request Check List
+
+This is just a reminder about the most common mistakes. Please make sure that you tick all *appropriate* boxes. But please read our [contribution guide](http://www.attrs.org/en/latest/contributing.html) at least once, it will save you unnecessary review cycles!
+
+- [ ] Added **tests** for changed code.
+- [ ] New features have been added to our [Hypothesis testing strategy](https://github.com/python-attrs/attrs/blob/master/tests/utils.py).
+- [ ] Updated **documentation** for changed code.
+- [ ] Documentation in `.rst` files is written using [semantic newlines](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
+- [ ] Changed/added classes/methods/functions have appropriate `versionadded`, `versionchanged`, or `deprecated` [directives](http://www.sphinx-doc.org/en/stable/markup/para.html#directive-versionadded).
+- [ ] Changes (and possible deprecations) are documented in [`CHANGELOG.rst`](https://github.com/python-attrs/attrs/blob/master/CHANGELOG.rst).
+
+If you have *any* questions to *any* of the points above, just **submit and ask**! This checklist is here to *help* you, not to deter you from contributing!
diff --git a/README.rst b/README.rst
index 0a5d03a..077de68 100644
--- a/README.rst
+++ b/README.rst
@@ -1,22 +1,25 @@
-=====================================
-attrs: Attributes Without Boilerplate
-=====================================
+.. image:: http://www.attrs.org/en/latest/_static/attrs_logo.png
+ :alt: attrs Logo
+
+==================================
+attrs: Classes Without Boilerplate
+==================================
.. image:: https://readthedocs.org/projects/attrs/badge/?version=stable
- :target: http://attrs.readthedocs.io/en/stable/?badge=stable
+ :target: http://www.attrs.org/en/stable/?badge=stable
:alt: Documentation Status
-.. image:: https://travis-ci.org/hynek/attrs.svg?branch=master
- :target: https://travis-ci.org/hynek/attrs
- :alt: CI status
+.. image:: https://travis-ci.org/python-attrs/attrs.svg?branch=master
+ :target: https://travis-ci.org/python-attrs/attrs
+ :alt: CI Status
-.. image:: https://codecov.io/github/hynek/attrs/branch/master/graph/badge.svg
- :target: https://codecov.io/github/hynek/attrs
- :alt: Test Coverage
+.. image:: https://codecov.io/github/python-attrs/attrs/branch/master/graph/badge.svg
+ :target: https://codecov.io/github/python-attrs/attrs
+ :alt: Test Coverage
.. teaser-begin
-``attrs`` is the Python package that will bring back the **joy** of **writing classes** by relieving you from the drudgery of implementing object protocols (aka `dunder <http://nedbatchelder.com/blog/200605/dunder.html>`_ methods).
+``attrs`` is the Python package that will bring back the **joy** of **writing classes** by relieving you from the drudgery of implementing object protocols (aka `dunder <https://nedbatchelder.com/blog/200605/dunder.html>`_ methods).
Its main goal is to help you to write **concise** and **correct** software without slowing down your code.
@@ -30,28 +33,28 @@ For that, it gives you a class decorator and a way to declaratively define the a
>>> import attr
>>> @attr.s
- ... class C(object):
- ... x = attr.ib(default=42)
- ... y = attr.ib(default=attr.Factory(list))
+ ... class SomeClass(object):
+ ... a_number = attr.ib(default=42)
+ ... list_of_numbers = attr.ib(default=attr.Factory(list))
...
- ... def hard_math(self, z):
- ... return self.x * self.y * z
- >>> i = C(x=1, y=2)
- >>> i
- C(x=1, y=2)
- >>> i.hard_math(3)
- 6
- >>> i == C(1, 2)
+ ... def hard_math(self, another_number):
+ ... return self.a_number + sum(self.list_of_numbers) * another_number
+ >>> sc = SomeClass(1, [1, 2, 3])
+ >>> sc
+ SomeClass(a_number=1, list_of_numbers=[1, 2, 3])
+ >>> sc.hard_math(3)
+ 19
+ >>> sc == SomeClass(1, [1, 2, 3])
True
- >>> i != C(2, 1)
+ >>> sc != SomeClass(2, [3, 2, 1])
True
- >>> attr.asdict(i)
- {'y': 2, 'x': 1}
- >>> C()
- C(x=42, y=[])
- >>> C2 = attr.make_class("C2", ["a", "b"])
- >>> C2("foo", "bar")
- C2(a='foo', b='bar')
+ >>> attr.asdict(sc)
+ {'a_number': 1, 'list_of_numbers': [1, 2, 3]}
+ >>> SomeClass()
+ SomeClass(a_number=42, list_of_numbers=[])
+ >>> C = attr.make_class("C", ["a", "b"])
+ >>> C("foo", "bar")
+ C(a='foo', b='bar')
After *declaring* your attributes ``attrs`` gives you:
@@ -74,15 +77,26 @@ Never again violate the `single responsibility principle <https://en.wikipedia.o
Testimonials
============
- I’m looking forward to is being able to program in Python-with-attrs everywhere.
- It exerts a subtle, but positive, design influence in all the codebases I’ve see it used in.
+ *I’m looking forward to is being able to program in Python-with-attrs everywhere.
+ It exerts a subtle, but positive, design influence in all the codebases I’ve see it used in.*
+
+ -- **Glyph Lefkowitz**, creator of `Twisted <https://twistedmatrix.com/>`_, `Automat <https://pypi.python.org/pypi/Automat>`_, and other open source software, in `The One Python Library Everyone Needs <https://glyph.twistedmatrix.com/2016/08/attrs.html>`_
+
+
+ *I'm increasingly digging your attr.ocity. Good job!*
+
+ -- **Łukasz Langa**, prolific CPython core developer and Production Engineer at Facebook
- -- Glyph Lefkowitz, inventor of Twisted and Software Developer at Rackspace in `The One Python Library Everyone Needs <https://glyph.twistedmatrix.com/2016/08/attrs.html>`_
+ *Writing a fully-functional class using attrs takes me less time than writing this testimonial.*
- I'm increasingly digging your attr.ocity. Good job!
+ -- **Amber Hawkie Brown**, Twisted Release Manager and Computer Owl
+
+
+ *attrs—classes for humans. I like it.*
+
+ -- **Kenneth Reitz**, author of `requests <http://www.python-requests.org/>`_, Python Overlord at Heroku, `on paper no less <https://twitter.com/hynek/status/866817877650751488>`_
- -- Łukasz Langa, prolific CPython core developer and Production Engineer at Facebook
.. -end-
@@ -91,8 +105,10 @@ Testimonials
Project Information
===================
-``attrs`` is released under the `MIT <http://choosealicense.com/licenses/mit/>`_ license,
-its documentation lives at `Read the Docs <https://attrs.readthedocs.io/>`_,
-the code on `GitHub <https://github.com/hynek/attrs>`_,
+``attrs`` is released under the `MIT <https://choosealicense.com/licenses/mit/>`_ license,
+its documentation lives at `Read the Docs <http://www.attrs.org/>`_,
+the code on `GitHub <https://github.com/python-attrs/attrs>`_,
and the latest release on `PyPI <https://pypi.org/project/attrs/>`_.
It’s rigorously tested on Python 2.7, 3.4+, and PyPy.
+
+If you'd like to contribute you're most welcome and we've written `a little guide <http://www.attrs.org/en/latest/contributing.html>`_ to get you started!
diff --git a/conftest.py b/conftest.py
index 93609c6..be9968c 100644
--- a/conftest.py
+++ b/conftest.py
@@ -1,15 +1,12 @@
from __future__ import absolute_import, division, print_function
-import os
-
import pytest
-from hypothesis import settings
@pytest.fixture(scope="session")
def C():
"""
- Return a simple but fully features attrs class with an x and a y attribute.
+ Return a simple but fully featured attrs class with an x and a y attribute.
"""
from attr import attributes, attr
diff --git a/dev-requirements.txt b/dev-requirements.txt
index 1729667..ce39a48 100644
--- a/dev-requirements.txt
+++ b/dev-requirements.txt
@@ -3,3 +3,4 @@ pytest
zope.interface
pympler
hypothesis
+six
diff --git a/docs-requirements.txt b/docs-requirements.txt
new file mode 100644
index 0000000..c473e1e
--- /dev/null
+++ b/docs-requirements.txt
@@ -0,0 +1,3 @@
+-e .
+sphinx
+zope.interface
diff --git a/docs/_static/attrs_logo.png b/docs/_static/attrs_logo.png
new file mode 100644
index 0000000..11b6e6f
Binary files /dev/null and b/docs/_static/attrs_logo.png differ
diff --git a/docs/api.rst b/docs/api.rst
index b3cb60a..edbe891 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -18,7 +18,7 @@ What follows is the API explanation, if you'd like a more hands-on introduction,
Core
----
-.. autofunction:: attr.s(these=None, repr_ns=None, repr=True, cmp=True, hash=True, init=True, slots=False, frozen=False, str=False)
+.. autofunction:: attr.s(these=None, repr_ns=None, repr=True, cmp=True, hash=None, init=True, slots=False, frozen=False, str=False)
.. note::
@@ -50,6 +50,27 @@ Core
``attrs`` also comes with a serious business alias ``attr.attrib``.
+ The object returned by :func:`attr.ib` also allows for setting the default and the validator using decorators:
+
+ .. doctest::
+
+ >>> @attr.s
+ ... class C(object):
+ ... x = attr.ib()
+ ... y = attr.ib()
+ ... @x.validator
+ ... def name_can_be_anything(self, attribute, value):
+ ... if value < 0:
+ ... raise ValueError("x must be positive")
+ ... @y.default
+ ... def name_does_not_matter(self):
+ ... return self.x + 1
+ >>> C(1)
+ C(x=1, y=2)
+ >>> C(-1)
+ Traceback (most recent call last):
+ ...
+ ValueError: x must be positive
.. autoclass:: attr.Attribute
@@ -69,7 +90,7 @@ Core
... class C(object):
... x = attr.ib()
>>> C.x
- Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({}))
+ Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({}))
.. autofunction:: attr.make_class
@@ -98,13 +119,20 @@ Core
>>> @attr.s
... class C(object):
... x = attr.ib(default=attr.Factory(list))
+ ... y = attr.ib(default=attr.Factory(
+ ... lambda self: set(self.x),
+ ... takes_self=True)
+ ... )
>>> C()
- C(x=[])
+ C(x=[], y=set())
+ >>> C([1, 2, 3])
+ C(x=[1, 2, 3], y={1, 2, 3})
.. autoexception:: attr.exceptions.FrozenInstanceError
.. autoexception:: attr.exceptions.AttrsAttributeNotFoundError
.. autoexception:: attr.exceptions.NotAnAttrsClassError
+.. autoexception:: attr.exceptions.DefaultAlreadySetError
.. _helpers:
@@ -125,9 +153,9 @@ Helpers
... x = attr.ib()
... y = attr.ib()
>>> attr.fields(C)
- (Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({})), Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({})))
+ (Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({})), Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({})))
>>> attr.fields(C)[1]
- Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=True, init=True, convert=None, metadata=mappingproxy({}))
+ Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({}))
>>> attr.fields(C).y is attr.fields(C)[1]
True
@@ -158,7 +186,7 @@ Helpers
... x = attr.ib()
... y = attr.ib()
>>> attr.asdict(C(1, C(2, 3)))
- {'y': {'y': 3, 'x': 2}, 'x': 1}
+ {'x': 1, 'y': {'x': 2, 'y': 3}}
.. autofunction:: attr.astuple
@@ -182,7 +210,7 @@ Helpers
See :ref:`asdict` for examples.
-.. autofunction:: assoc
+.. autofunction:: attr.evolve
For example:
@@ -195,12 +223,19 @@ See :ref:`asdict` for examples.
>>> i1 = C(1, 2)
>>> i1
C(x=1, y=2)
- >>> i2 = attr.assoc(i1, y=3)
+ >>> i2 = attr.evolve(i1, y=3)
>>> i2
C(x=1, y=3)
>>> i1 == i2
False
+ ``evolve`` creates a new instance using ``__init__``.
+ This fact has several implications:
+
+ * private attributes should be specified without the leading underscore, just like in ``__init__``.
+ * attributes with ``init=False`` can't be set with ``evolve``.
+ * the usual ``__init__`` validators will validate the new values.
+
.. autofunction:: validate
For example:
@@ -215,7 +250,7 @@ See :ref:`asdict` for examples.
>>> attr.validate(i)
Traceback (most recent call last):
...
- TypeError: ("'x' must be <type 'int'> (got '1' that is a <type 'str'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=True, init=True), <type 'int'>, '1')
+ TypeError: ("'x' must be <type 'int'> (got '1' that is a <type 'str'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=None, init=True), <type 'int'>, '1')
Validators can be globally disabled if you want to run them only in development and tests but not in production because you fear their performance impact:
@@ -252,11 +287,44 @@ Validators
>>> C(None)
Traceback (most recent call last):
...
- TypeError: ("'x' must be <type 'int'> (got None that is a <type 'NoneType'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=True, init=True), <type 'int'>, None)
+ TypeError: ("'x' must be <type 'int'> (got None that is a <type 'NoneType'>).", Attribute(name='x', default=NOTHING, validator=<instance_of validator for type <type 'int'>>, repr=True, cmp=True, hash=None, init=True), <type 'int'>, None)
+.. autofunction:: attr.validators.in_
+
+ For example:
+
+ .. doctest::
+
+ >>> import enum
+ >>> class State(enum.Enum):
+ ... ON = "on"
+ ... OFF = "off"
+ >>> @attr.s
+ ... class C(object):
+ ... state = attr.ib(validator=attr.validators.in_(State))
+ ... val = attr.ib(validator=attr.validators.in_([1, 2, 3]))
+ >>> C(State.ON, 1)
+ C(state=<State.ON: 'on'>, val=1)
+ >>> C("on", 1)
+ Traceback (most recent call last):
+ ...
+ ValueError: 'state' must be in <enum 'State'> (got 'on')
+ >>> C(State.ON, 4)
+ Traceback (most recent call last):
+ ...
+ ValueError: 'val' must be in [1, 2, 3] (got 4)
.. autofunction:: attr.validators.provides
+.. autofunction:: attr.validators.and_
+
+ For convenience, it's also possible to pass a list to :func:`attr.ib`'s validator argument.
+
+ Thus the following two statements are equivalent::
+
+ x = attr.ib(validator=attr.validators.and_(v1, v2, v3))
+ x = attr.ib(validator=[v1, v2, v3])
+
.. autofunction:: attr.validators.optional
For example:
@@ -276,8 +344,28 @@ Validators
C(x=None)
+Converters
+----------
+
+.. autofunction:: attr.converters.optional
+
+ For example:
+
+ .. doctest::
+
+ >>> @attr.s
+ ... class C(object):
+ ... x = attr.ib(convert=attr.converters.optional(int))
+ >>> C(None)
+ C(x=None)
+ >>> C(42)
+ C(x=42)
+
+
Deprecated APIs
---------------
The serious business aliases used to be called ``attr.attributes`` and ``attr.attr``.
There are no plans to remove them but they shouldn't be used in new code.
+
+.. autofunction:: assoc
diff --git a/docs/conf.py b/docs/conf.py
index dbfdf36..bc5dfed 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,26 +1,9 @@
# -*- coding: utf-8 -*-
-#
-# attrs documentation build configuration file, created by
-# sphinx-quickstart on Sun May 11 16:17:15 2014.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
import codecs
import os
import re
-try:
- import sphinx_rtd_theme
-except ImportError:
- sphinx_rtd_theme = None
-
def read(*parts):
"""
@@ -44,16 +27,9 @@ def find_version(*file_paths):
return version_match.group(1)
raise RuntimeError("Unable to find version string.")
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
@@ -71,9 +47,6 @@ templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
# The master toctree document.
master_doc = 'index'
@@ -90,177 +63,67 @@ release = find_version("../src/attr/__init__.py")
version = release.rsplit(u".", 1)[0]
# The full version, including alpha/beta/rc tags.
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
+add_function_parentheses = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
... 2749 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-attrs.git
More information about the Python-modules-commits
mailing list