Rooba
/
attrs
mirror of https://github.com/python-attrs/attrs.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity
attrs/docs/index.rst

94 lines
3.0 KiB
ReStructuredText
Raw Normal View History

Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
======================================
``attrs``: Classes Without Boilerplate
======================================
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
Release v\ |release| (`What's new? <changelog>`).
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
.. include:: ../README.rst
Gut docs for now
2015-01-27 21:41:24 +00:00
:start-after: teaser-begin
More documentation polish
2016-08-15 15:24:09 +00:00
:end-before: -spiel-end-
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
Getting Started
===============
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
``attrs`` is a Python-only package `hosted on PyPI <https://pypi.org/project/attrs/>`_.
The recommended installation method is `pip <https://pip.pypa.io/en/stable/>`_-installing into a `virtualenv <https://hynek.me/articles/virtualenv-lives/>`_:
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
.. code-block:: console
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
$ pip install attrs
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
The next three steps should bring you up and running in no time:
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
- `overview` will show you a simple example of ``attrs`` in action and introduce you to its philosophy.
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
Afterwards, you can start writing your own classes, understand what drives ``attrs``'s design, and know what ``@attr.s`` and ``attr.ib()`` stand for.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
- `examples` will give you a comprehensive tour of ``attrs``'s features.
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
After reading, you will know about our advanced features and how to use them.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
- Finally `why` gives you a rundown of potential alternatives and why we think ``attrs`` is superior.
Add narrative docs for type annotations (#406) * Add narrative docs for type annotations * Better wording * Use better code-block types * Add newsfragment for #238 that refers to these docs
2018-07-28 11:05:12 +00:00
Yes, we've heard about ``namedtuple``\ s and Data Classes!
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
- If at any point you get confused by some terminology, please check out our `glossary`.
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
If you need any help while getting started, feel free to use the ``python-attrs`` tag on `StackOverflow <https://stackoverflow.com/questions/tagged/python-attrs>`_ and someone will surely help you out!
Day-to-Day Usage
================
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
- `types` help you to write *correct* and *self-documenting* code.
``attrs`` has first class support for them and even allows you to drop the calls to `attr.ib` on modern Python versions!
Add narrative chapter about initialization (#370) * Add narrative chapter on initialization * Be more explicit about defining validators both ways * Stress that the name of default/validator != attr name * Mention nested schemas * Explain handling of private attributes * Add another consequence of _ stripping * Stress that nothing should overwrite attributes on class body * Better wording * typo * Dedup examples * Address review feedback * Add newsfragments
2018-04-24 22:07:03 +00:00
- Instance initialization is one of ``attrs`` key feature areas.
Our goal is to relieve you from writing as much code as possible.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
`init` gives you an overview what ``attrs`` has to offer and explains some related philosophies we believe in.
Add a narrative chapter on object hashing (#369) * Add a narrative chapter on object hashing * Simplify * Add a "what to do" to the tl;dr warning * Shuffle around * Fix typos
2018-04-16 05:49:34 +00:00
- If you want to put objects into sets or use them as keys in dictionaries, they have to be hashable.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
The simplest way to do that is to use frozen classes, but the topic is more complex than it seems and `hashing` will give you a primer on what to look out for.
- Once you're comfortable with the concepts, our `api` contains all information you need to use ``attrs`` to its fullest.
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
- ``attrs`` is built for extension from the ground up.
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
`extending` will show you the affordances it offers and how to make it a building block of your own projects.
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Don't strip teaser
2015-01-28 17:23:15 +00:00
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
.. include:: ../README.rst
:start-after: -testimonials-
:end-before: -end-
More copyediting The correct parts being based on feedback from @econchick
2016-08-17 11:28:00 +00:00
.. include:: ../README.rst
:start-after: -project-information-
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
.. toctree::
:maxdepth: 1
license
Pull license up
2016-08-15 19:51:20 +00:00
backward-compatibility
Add Python 2 statement (#498)
2019-02-10 06:32:19 +00:00
python-2
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
contributing
changelog
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
----
Full Table of Contents
======================
.. toctree::
:maxdepth: 2
overview
why
examples
Add narrative docs for type annotations (#406) * Add narrative docs for type annotations * Better wording * Use better code-block types * Add newsfragment for #238 that refers to these docs
2018-07-28 11:05:12 +00:00
types
Add narrative chapter about initialization (#370) * Add narrative chapter on initialization * Be more explicit about defining validators both ways * Stress that the name of default/validator != attr name * Mention nested schemas * Explain handling of private attributes * Add another consequence of _ stripping * Stress that nothing should overwrite attributes on class body * Better wording * typo * Dedup examples * Address review feedback * Add newsfragments
2018-04-24 22:07:03 +00:00
init
Add a narrative chapter on object hashing (#369) * Add a narrative chapter on object hashing * Simplify * Add a "what to do" to the tl;dr warning * Shuffle around * Fix typos
2018-04-16 05:49:34 +00:00
hashing
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
api
extending
how-does-it-work
Add glossary & make slotted classes official (#371) * Add glossary & make slotted classes official * Add missing import
2018-05-02 05:24:04 +00:00
glossary
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
Initial commit Docs aren't there yet
2015-01-27 16:53:17 +00:00
Indices and tables
==================
Add default_role for Sphinx. (#571) * Add default_role for Sphinx. Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable. * Remove the roles from builtin objects to demo any. * Style. * Add z.i to intersphinx. Enables the link to z.i.Interface. * Enable nitpick mode. Fix the remaining broken links or whitelist them via nitpick_ignore. * Kill all :func:s. * Kill all :class:es. * Kill all :doc:s. * Kill all :ref:s. Except one, that probably meant :func:, and which is a duplicate ref. * Kill :exc: and :data:. * Kill :mod:s. * Kill new explicit refs from the merge.
2019-09-09 13:02:16 +00:00
* `genindex`
* `search`