From 41d8cce09da9a73634648145cbcef30c282a0811 Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Tue, 30 Aug 2016 12:12:02 +0200
Subject: [PATCH] Add a philosophy section (#73)

Also expand the example class a little bit to stress that we're not just
about data containers.
---
 README.rst        |  5 +++++
 docs/api.rst      |  2 ++
 docs/overview.rst | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/README.rst b/README.rst
index a3c1178baf87bfa..bcb4c0896377b6d 100644
--- a/README.rst
+++ b/README.rst
@@ -33,9 +33,14 @@ For that, it gives you a class decorator and a way to declaratively define the a
    ... class C(object):
    ...     x = attr.ib(default=42)
    ...     y = 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)
    True
    >>> i != C(2, 1)
diff --git a/docs/api.rst b/docs/api.rst
index 4983327c1c38d38..423e45dfea9f1cb 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -105,6 +105,8 @@ Core
 .. autoexception:: attr.exceptions.FrozenInstanceError
 
 
+.. _helpers:
+
 Helpers
 -------
 
diff --git a/docs/overview.rst b/docs/overview.rst
index 0d95c4aab2c9a82..6070b8066be56b5 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -9,6 +9,39 @@ In order to fullfil its ambitious goal of bringing back the joy to writing class
    :end-before: -testimonials-
 
 
+.. _philosophy:
+
+Philosophy
+==========
+
+It's about regular classes.
+   ``attrs`` for creating well-behaved classes with a type, attributes, methods, and everything that comes with a class.
+   It can be used for data-only containers like ``namedtuple``\ s or ``types.SimpleNamespace`` but they're just a sub-genre of what ``attrs`` is good for.
+
+The class belongs to the users.
+   You define a class and ``attrs`` adds static methods to that class based on the attributes you declare.
+   The end.
+   It doesn't add meta classes.
+   It doesn't add classes you've never heard of to your inheritance tree.
+   An ``attrs`` class in runtime is indistiguishable from a regular class: because it *is* a regular class with a few boilerplate-y methods attached.
+
+Be light on API impact.
+   As convenient as it seems at first, ``attrs`` will *not* tack on any methods to your classes save the dunder ones.
+   Hence all the useful :ref:`tools <helpers>` that come with ``attrs`` live in functions that operate on top of instances.
+   Since they take an ``attrs`` instance as their first argument, you can attach them to your classes with one line of code.
+
+Performance matters.
+   ``attrs`` runtime impact is very close to zero because all the work is done when the class is defined.
+   Once you're instantiating it, ``attrs`` is out of the picture completely.
+
+No surprises.
+   ``attrs`` creates classes that arguably work the way a Python beginner would reasonably expect them to work.
+   It doesn't try to guess what you mean because explicit is better than implicit.
+   It doesn't try to be clever because software shouldn't be clever.
+
+Check out :doc:`how-does-it-work` if you'd like to know how it achieves all of the above.
+
+
 What ``attrs`` Is Not
 =====================