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

101 lines
3.3 KiB
ReStructuredText
Raw Normal View History

create a :mod:`attr` and :mod:`attrs` for intersphinx links to the package itself (#850) * Try to create a :mod:`attr` and :mod:`attrs` https://github.com/python-attrs/attrs/issues/849 * Update index.rst * Update index.rst * Update index.rst
2021-10-12 12:55:26 +00:00
.. module:: attr
.. module:: attrs
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
Refactor docs and switch to RTD theme Our API docs are much more readable on it. Remove testimonials, they don't serve that much and take up space. Slightly refactor main docs page.
2020-03-08 06:30:03 +00:00
:end-before: teaser-end
More documentation polish
2016-08-15 15:24:09 +00:00
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
Refactor docs and switch to RTD theme Our API docs are much more readable on it. Remove testimonials, they don't serve that much and take up space. Slightly refactor main docs page.
2020-03-08 06:30:03 +00:00
$ python -m 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.
Document the various core names and why they exist (#871) * Document the various core names and why they exist Signed-off-by: Hynek Schlawack <hs@ox.cx> * Remove stray backtick * Add example of new API * Link PEP 526 * future is now * phrase and typos * typo/grammar * typo * Better phrasing * Add missing and * less words = better * polish * phrasing * looks weird but is correct * comma spliiiiceeeee * example * make it sound less dry * fix * phrasing
2021-11-24 08:39:41 +00:00
Afterwards, you can start writing your own classes and understand what drives ``attrs``'s design.
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.
Document the various core names and why they exist (#871) * Document the various core names and why they exist Signed-off-by: Hynek Schlawack <hs@ox.cx> * Remove stray backtick * Add example of new API * Link PEP 526 * future is now * phrase and typos * typo/grammar * typo * Better phrasing * Add missing and * less words = better * polish * phrasing * looks weird but is correct * comma spliiiiceeeee * example * make it sound less dry * fix * phrasing
2021-11-24 08:39:41 +00:00
- If you're confused by all the ``attr.s``, ``attr.ib``, ``attrs``, ``attrib``, ``define``, ``frozen``, and ``field``, head over to `names` for a very short explanation, and optionally a quick history lesson.
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
Stack Overflow is two words
2021-10-28 05:11:16 +00:00
If you need any help while getting started, feel free to use the ``python-attrs`` tag on `Stack Overflow <https://stackoverflow.com/questions/tagged/python-attrs>`_ and someone will surely help you out!
Prepare for narrative docs (#275)
2017-10-26 15:55:45 +00:00
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.
Document comparison (#768) * Document comparison * Grammar * Stress independence of eq/order * Add example for eq * Be consistent with fields * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Clarify Co-authored-by: Julian Berman <Julian@GrayVines.com>
2021-02-26 06:53:57 +00:00
- Comparing and ordering objects is a common task.
`comparison` shows you how ``attrs`` helps you with that and how you can customize it.
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
Refactor docs and switch to RTD theme Our API docs are much more readable on it. Remove testimonials, they don't serve that much and take up space. Slightly refactor main docs page.
2020-03-08 06:30:03 +00:00
:start-after: -getting-help-
:end-before: -project-information-
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
----
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
Document comparison (#768) * Document comparison * Grammar * Stress independence of eq/order * Add example for eq * Be consistent with fields * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Update docs/comparison.rst Co-authored-by: Julian Berman <Julian@GrayVines.com> * Clarify Co-authored-by: Julian Berman <Julian@GrayVines.com>
2021-02-26 06:53:57 +00:00
comparison
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
Document the various core names and why they exist (#871) * Document the various core names and why they exist Signed-off-by: Hynek Schlawack <hs@ox.cx> * Remove stray backtick * Add example of new API * Link PEP 526 * future is now * phrase and typos * typo/grammar * typo * Better phrasing * Add missing and * less words = better * polish * phrasing * looks weird but is correct * comma spliiiiceeeee * example * make it sound less dry * fix * phrasing
2021-11-24 08:39:41 +00:00
names
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
Refactor docs and switch to RTD theme Our API docs are much more readable on it. Remove testimonials, they don't serve that much and take up space. Slightly refactor main docs page.
2020-03-08 06:30:03 +00:00
.. include:: ../README.rst
:start-after: -project-information-
.. toctree::
:maxdepth: 1
license
python-2
changelog
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`