Skip to content

Commit 74dd743

Browse files
author
Scott Sanderson
committed
DOC: Docs.
1 parent 295907a commit 74dd743

File tree

13 files changed

+924
-106
lines changed

13 files changed

+924
-106
lines changed

‎README.rst

Lines changed: 9 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -3,99 +3,21 @@
33

44
|build status|
55

6+
``interface`` is a library for declaring interfaces and for statically
7+
asserting that classes implement those interfaces. It aims to provide stricter
8+
semantics and better error messages than Python's built-in ``abc`` module.
9+
10+
``interface`` supports Python 2.7 and Python 3.4+.
11+
12+
For more information, see our `documentation`_.
13+
614
Installation
715
~~~~~~~~~~~~
816

917
.. code-block:: shell
1018
1119
$ pip install python-interface
1220
21+
.. _`documentation` : interface.readthedocs.io
1322
.. |build status| image:: https://travis-ci.org/ssanderson/interface.svg?branch=master
1423
:target: https://travis-ci.org/ssanderson/interface
15-
16-
``interface`` provides facilities for declaring interfaces and for statically
17-
asserting that classes implement those interfaces. It supports Python 2.7 and
18-
Python 3.4+.
19-
20-
``interface`` improves on Python's ``abc`` module in two ways:
21-
22-
1. Interface requirements are checked at class creation time, rather than at
23-
instance creation time. This means that ``interface`` can tell you if a
24-
class fails to meet the requirements of an interface even if you never
25-
create any instances of that class.
26-
27-
2. ``interface`` requires that method signatures of interface implementations
28-
are compatible with the signatures declared in the interface. For example,
29-
the following code using ``abc`` does not produce an error:
30-
31-
.. code-block:: python
32-
33-
>>> from abc import ABCMeta, abstractmethod
34-
>>> class Base(metaclass=ABCMeta):
35-
... @abstractmethod
36-
... def method(self, a, b):
37-
... pass
38-
...
39-
>>> class Implementation(MyABC):
40-
... def method(self):
41-
... return "This shouldn't work."
42-
...
43-
>>> impl = Implementation()
44-
>>>
45-
46-
The equivalent code using ``interface`` produces an error indicating that
47-
the signature of our implementation method is incompatible with the
48-
signature of our interface declaration:
49-
50-
.. code-block:: python
51-
52-
>>> from interface import implements, Interface
53-
>>> class I(Interface):
54-
... def method(self, a, b):
55-
... pass
56-
...
57-
>>> class C(implements(I)):
58-
... def method(self):
59-
... return "This shouldn't work"
60-
...
61-
TypeError:
62-
class C failed to implement interface I:
63-
64-
The following methods were implemented but had invalid signatures:
65-
- method(self) != method(self, a, b)
66-
67-
Defining an Interface
68-
~~~~~~~~~~~~~~~~~~~~~
69-
70-
To define an interface, simply subclass from ``interface.Interface`` and define
71-
method stubs in your class body.
72-
73-
.. code-block:: python
74-
75-
from interface import Interface
76-
77-
class MyInterface(Interface):
78-
79-
def method1(self):
80-
pass
81-
82-
def method2(self, arg1, arg2):
83-
pass
84-
85-
Implementing an Interface
86-
~~~~~~~~~~~~~~~~~~~~~~~~~
87-
88-
To declare that a particular class implements an interface ``I``, pass
89-
``implements(I)`` as a base class for your class.
90-
91-
.. code-block:: python
92-
93-
from interface import implements
94-
95-
class MyClass(implements(MyInterface)):
96-
97-
def method1(self):
98-
return "method1"
99-
100-
def method2(self, arg1, arg2):
101-
return "method2"

‎docs/Makefile

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = interface
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
22+
autobuild:
23+
sphinx-autobuild -p 9999 -b html "$(SOURCEDIR)" $(BUILDDIR)/html

‎docs/abc.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
:mod:`interface` vs. :mod:`abc`
2+
-------------------------------
3+
4+
The Python standard library :mod:`abc` (**A**\bstract **B**\ase **C**\lass)
5+
module is often used to define and verify interfaces.
6+
7+
:mod:`interface` differs from Python's :mod:`abc` module in two important ways:
8+
9+
1. Interface requirements are checked at class creation time, rather than at
10+
instance creation time. This means that :mod:`interface` can tell you if a
11+
class fails to implement an interface even if you never create any instances
12+
of that class.
13+
14+
2. :mod:`interface` requires that method signatures of implementations are
15+
compatible with signatures declared in interfaces. For example, the
16+
following code using :mod:`abc` does not produce an error:
17+
18+
.. code-block:: python
19+
20+
>>> from abc import ABCMeta, abstractmethod
21+
>>> class Base(metaclass=ABCMeta):
22+
...
23+
... @abstractmethod
24+
... def method(self, a, b):
25+
... pass
26+
...
27+
>>> class Implementation(MyABC):
28+
...
29+
... def method(self): # Missing a and b parameters.
30+
... return "This shouldn't work."
31+
...
32+
>>> impl = Implementation()
33+
>>>
34+
35+
The equivalent code using :mod:`interface` produces an error telling us that
36+
the implementation method doesn't match the interface:
37+
38+
.. code-block:: python
39+
40+
>>> from interface import implements, Interface
41+
>>> class I(Interface):
42+
... def method(self, a, b):
43+
... pass
44+
...
45+
>>> class C(implements(I)):
46+
... def method(self):
47+
... return "This shouldn't work"
48+
...
49+
TypeError:
50+
class C failed to implement interface I:
51+
52+
The following methods were implemented but had invalid signatures:
53+
- method(self) != method(self, a, b)

‎docs/api-reference.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
API Reference
2+
-------------
3+
4+
.. py:currentmodule:: interface
5+
6+
.. autoclass:: Interface
7+
:members: from_class
8+
9+
.. autofunction:: implements
10+
11+
.. autoclass:: default

‎docs/conf.py

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/stable/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
# import os
16+
# import sys
17+
# sys.path.insert(0, os.path.abspath('.'))
18+
19+
20+
# -- Project information -----------------------------------------------------
21+
22+
project = 'interface'
23+
copyright = '2018, Scott Sanderson'
24+
author = 'Scott Sanderson'
25+
26+
# The short X.Y version
27+
version = ''
28+
# The full version, including alpha/beta/rc tags
29+
release = '1.4.0'
30+
31+
32+
# -- General configuration ---------------------------------------------------
33+
34+
# If your documentation needs a minimal Sphinx version, state it here.
35+
#
36+
# needs_sphinx = '1.0'
37+
38+
# Add any Sphinx extension module names here, as strings. They can be
39+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40+
# ones.
41+
extensions = [
42+
'sphinx.ext.autodoc',
43+
'sphinx.ext.doctest',
44+
'sphinx.ext.intersphinx',
45+
'sphinx.ext.todo',
46+
'sphinx.ext.viewcode',
47+
'sphinx.ext.napoleon',
48+
'sphinx.ext.autosummary',
49+
]
50+
51+
# Add any paths that contain templates here, relative to this directory.
52+
templates_path = ['_templates']
53+
54+
# The suffix(es) of source filenames.
55+
# You can specify multiple suffix as a list of string:
56+
#
57+
# source_suffix = ['.rst', '.md']
58+
source_suffix = '.rst'
59+
60+
# The master toctree document.
61+
master_doc = 'index'
62+
63+
# The language for content autogenerated by Sphinx. Refer to documentation
64+
# for a list of supported languages.
65+
#
66+
# This is also used if you do content translation via gettext catalogs.
67+
# Usually you set "language" from the command line for these cases.
68+
language = None
69+
70+
# List of patterns, relative to source directory, that match files and
71+
# directories to ignore when looking for source files.
72+
# This pattern also affects html_static_path and html_extra_path .
73+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
74+
75+
# The name of the Pygments (syntax highlighting) style to use.
76+
pygments_style = 'sphinx'
77+
78+
79+
# -- Options for HTML output -------------------------------------------------
80+
81+
# The theme to use for HTML and HTML Help pages. See the documentation for
82+
# a list of builtin themes.
83+
#
84+
html_theme = 'sphinx_rtd_theme'
85+
86+
# Theme options are theme-specific and customize the look and feel of a theme
87+
# further. For a list of options available for each theme, see the
88+
# documentation.
89+
#
90+
# html_theme_options = {}
91+
92+
# Add any paths that contain custom static files (such as style sheets) here,
93+
# relative to this directory. They are copied after the builtin static files,
94+
# so a file named "default.css" will overwrite the builtin "default.css".
95+
html_static_path = ['_static']
96+
97+
# Custom sidebar templates, must be a dictionary that maps document names
98+
# to template names.
99+
#
100+
# The default sidebars (for documents that don't match any pattern) are
101+
# defined by theme itself. Builtin themes are using these templates by
102+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
103+
# 'searchbox.html']``.
104+
#
105+
# html_sidebars = {}
106+
107+
108+
# -- Options for HTMLHelp output ---------------------------------------------
109+
110+
# Output file base name for HTML help builder.
111+
htmlhelp_basename = 'interfacedoc'
112+
113+
114+
# -- Options for LaTeX output ------------------------------------------------
115+
116+
latex_elements = {
117+
# The paper size ('letterpaper' or 'a4paper').
118+
#
119+
# 'papersize': 'letterpaper',
120+
121+
# The font size ('10pt', '11pt' or '12pt').
122+
#
123+
# 'pointsize': '10pt',
124+
125+
# Additional stuff for the LaTeX preamble.
126+
#
127+
# 'preamble': '',
128+
129+
# Latex figure (float) alignment
130+
#
131+
# 'figure_align': 'htbp',
132+
}
133+
134+
# Grouping the document tree into LaTeX files. List of tuples
135+
# (source start file, target name, title,
136+
# author, documentclass [howto, manual, or own class]).
137+
latex_documents = [
138+
(master_doc, 'interface.tex', 'interface Documentation',
139+
'Scott Sanderson', 'manual'),
140+
]
141+
142+
143+
# -- Options for manual page output ------------------------------------------
144+
145+
# One entry per manual page. List of tuples
146+
# (source start file, name, description, authors, manual section).
147+
man_pages = [
148+
(master_doc, 'interface', 'interface Documentation',
149+
[author], 1)
150+
]
151+
152+
153+
# -- Options for Texinfo output ----------------------------------------------
154+
155+
# Grouping the document tree into Texinfo files. List of tuples
156+
# (source start file, target name, title, author,
157+
# dir menu entry, description, category)
158+
texinfo_documents = [
159+
(master_doc, 'interface', 'interface Documentation',
160+
author, 'interface', 'One line description of project.',
161+
'Miscellaneous'),
162+
]
163+
164+
165+
# -- Extension configuration -------------------------------------------------
166+
167+
# -- Options for intersphinx extension ---------------------------------------
168+
169+
# Example configuration for intersphinx: refer to the Python standard library.
170+
intersphinx_mapping = {'https://docs.python.org/': None}
171+
172+
# -- Options for todo extension ----------------------------------------------
173+
174+
# If true, `todo` and `todoList` produce output, else they produce nothing.
175+
todo_include_todos = True

0 commit comments

Comments
 (0)