Add more descriptions for classes

Author: rinatz

docs/ch03-02-scopes.md

@@ -0,0 +1,11 @@
+# スコープ
+
+他の言語ではクラスメンバに対して `public, protected, private` といったアクセス指定子を指定することができますが Python ではそのような指定はできず、すべてのメンバが `public` として扱われます。ですが習慣的に下記のような命名規則でメンバのスコープを区別するようになっています。
+
+| スコープ  | 命名規則     |
+|-----------|--------------|
+| public    | `method()`   |
+| protected | `_method()`  |
+| private   | `__method()` |
+
+Python では `__method()` のような private メソッドを作ることはそれほど多くはありません。隠蔽したいメンバを定義するときは `_method()` のような protected メソッドを定義することのほうが多いです。

docs/ch03-03-special-attributes.md

@@ -0,0 +1,87 @@
+# 特殊属性
+
+新たなクラスを定義したときには自動で定義されるメンバやメソッドが存在しており、それらを特殊属性といいます。代表的な特殊属性をいくつか紹介します。
+
+下記のようなクラスを定義したときの特殊属性には次のようなものがあります。
+
+```python
+import math
+
+
+class Point:
+    """Point クラスです。"""
+
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+    def distance(self):
+        return math.sqrt(self.x * self.x + self.y * self.y)
+```
+
+## `__doc__`
+
+`Point.__doc__` という変数には `"""Point クラスです。"""` という文字列が入ります。`""" ... """` というトリプルクオテーションでくくられた文字列は改行を含む複数行の文字列を定義できる文字列です。
+
+```python
+"""この文字列は
+一つの文字列として
+扱われます。"""
+```
+
+`__doc__` は docstring と呼ばれ、ドキュメンテーションをする際に使用される文字列として扱われます。
+
+## `__init__`
+
+クラスインスタンスを作成するときは `__init__()` が呼び出されます。
+
+```python
+point = Point(10, 20)   # point.__init__(10, 20)
+```
+
+## `__getattribute__`
+
+クラスのメンバやメソッドを参照したときは `__getattribute__()` が呼び出されます。
+
+```python
+point = Point(10, 20)
+point.x             # point.__getattribute__('x')
+point.distance()    # point.__getattribute__('distance')()
+```
+
+## `__getattr__`
+
+`__getattribute__()` でのメンバ参照に失敗した場合は `__getattr__()` が呼び出されます。このような事が起こるのはクラスのメンバとして定義されていないものにアクセスしようとしたときに起こります。
+
+```python
+point.foo   # point.__getattr__('foo')
+```
+
+## `__setattr__`
+
+メンバへの代入が行われた場合は `__setattr__()` が呼び出されます。
+
+```python
+point = Point(10, 20)
+point.x = 30    # point.__setattr__('x', 30)
+```
+
+## `__eq__`
+
+インスタンスに対して `==` が使用された場合は `__eq__()` が呼ばれます。
+
+```python
+point1 = Point(10, 20)
+point2 = Point(30, 40)
+point1 == point2    # point1.__eq__(point2)
+```
+
+その他類似の特殊属性が下記の通り用意されています。
+
+| 特殊属性 | 意味               |
+|----------|--------------------|
+| `__ne__` | `point1 != point2` |
+| `__le__` | `point1 <= point2` |
+| `__lt__` | `point1 < point2`  |
+| `__ge__` | `point1 >= point2` |
+| `__gt__` | `point1 > point2`  |

docs/ch03-04-properties.md

@@ -0,0 +1,76 @@
+# プロパティ
+
+クラスのメンバで変数のように参照することのできる関数のことをプロパティといいます。
+
+```python
+import math
+
+
+class Point:
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+    @property
+    def distance(self):
+        return math.sqrt(self.x * self.x + self.y * self.y)
+```
+
+`@property` のように `@` ではじまるキーワードは **デコレータ** といって関数やクラスに特殊な振る舞いを注入することのできる機能になっています。`distance()` は関数として定義されていますが `@property` デコレータがついていると変数のように参照することができるようになります。
+
+```python
+point = Point(10, 20)
+point.distance  # 22.360679775
+```
+
+プロパティは `point.distance()` のように呼ぶことはできません。
+
+メンバ変数 `x, y` を隠蔽して、代わりにプロパティを提供すると代入ができなくなるので安全です。
+
+```python
+import math
+
+
+class Point:
+    def __init__(self, x, y):
+        # _ をつけて隠蔽していることを示す
+        self._x = x
+        self._y = y
+
+    @property
+    def x(self):
+        return self._x
+
+    @property
+    def y(self):
+        return self._y
+
+    @property
+    def distance(self):
+        return math.sqrt(self.x * self.x + self.y * self.y)
+```
+
+```python
+point = Point(10, 20)
+print(point.x, point.y)     # _x, _y の参照は可能
+point.x = 30                # _x, _y への代入はできない
+```
+
+プロパティに対して代入を行いたい場合は `setter` プロパティを定義します。
+
+```python
+@property
+def x(self):
+    return self._x      # getter
+
+@x.setter
+def x(self, value):
+    self._x = value     # setter
+```
+
+
+```python
+point.x = 30    # OK
+```
+
+プロパティの利点は `get_x()` のような関数を定義しなくても、まるで変数を直接参照しているようなコードが書ける点にあります。これはクラスを利用する人からするとシンプルなコードが書けるので便利です。ただしプロパティは変数と同じくらいに気軽に参照するメンバになるので、パフォーマンスが遅い関数をむやみにプロパティとして定義するのは避けたほうが良いです。

mkdocs.yml

@@ -56,6 +56,9 @@ nav:
     - 2.7. ラムダ式: ch02-07-lambdas.md
   - 3. クラス:
     - 3.1. クラス: ch03-01-classes.md
+    - 3.2. スコープ: ch03-02-scopes.md
+    - 3.3. 特殊属性: ch03-03-special-attributes.md
+    - 3.4. プロパティ: ch03-04-properties.md
   - 4. モジュールとパッケージ:
     - 4.1. モジュール: ch04-01-modules.md
     - 4.2. パッケージ: ch04-02-packages.md