コーディングスタイルと標準

Pylons プロジェクト配下のプロジェクトは、コーディングスタイル、テスト、 およびドキュメンテーションに関する厳格な標準を持っています。

ドキュメンテーションスタイル

すべてのプロジェクトは Sphinx を用いて ドキュメンテーションを構築する必要があり、一貫性のため Pylons Sphinx Theme を使用します。

Pylons テーマを使用してドキュメンテーションを構築するためには、 Sphinx の conf.py の先頭付近に次の定型文を加えてください:

import sys, os

# Add and use Pylons theme
# protect against dumb importers
if 'sphinx-build' in ' '.join(sys.argv):
    from subprocess import call, Popen, PIPE

    p = Popen('which git', shell=True, stdout=PIPE)
    git = p.stdout.read().strip()
    cwd = os.getcwd()
    _themes = os.path.join(cwd, '_themes')

    if not os.path.isdir(_themes):
        call([git,
              'clone',
              'git://github.com/Pylons/pylons_sphinx_theme.git',
               '_themes'])
    else:
        os.chdir(_themes)
        call([git, 'checkout', 'master'])
        call([git, 'pull'])
        os.chdir(cwd)

    sys.path.append(os.path.abspath('_themes'))

    parent = os.path.dirname(os.path.dirname(__file__))
    sys.path.append(os.path.abspath(parent))
    os.chdir(parent)

html_theme_path = ['_themes']
html_theme = 'pylons'
html_theme_options = {github_url:'https://github.com/Pylons/yourprojname'}

そして、この結果作られる _themes ディレクトリをバージョン管理システムの 中で無視するようにしてください。

これによってテーマを利用するプロジェクトを構築することが可能になります。 また、テーマに更新があった場合、ドキュメントが再構築される時にテーマの 変更が自動的に取得されます。

PDF 出力

docs/conf.py の中で latex_documents に以下の値を設定してください:

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
('latexindex', 'pyramid_<project name>.tex',
'Pyramid\_<project name>',
'Author', 'manual'),
    ]

LaTeX でのエラーを防ぐため、 \_ を使用してドキュメントタイトル中の下線 をエスケープすることは重要です。

以下の行をコメントにしてください:

#latex_logo = '_static/pylons_small.png'

フォルダ pyramid/docs/_static (2つの .png ファイルを含む) と、ファイル pyramid/docs/convert_images.shdocs/ フォルダにコピーしてください。

ePub 出力

docs/conf.py の中で epub_exclude_files に以下の値を必ず設定してください:

# A list of files that should not be packed into the epub file.
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
    '_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
    '_static/basic.css', 'search.html', '_static/websupport.js' ]

新機能コード要件

Pylons プロジェクトのすべてのパッケージで、機能を加えるために:

  • その機能を (docs/ にある) API ドキュメンテーションと narrative ドキュメンテーションの両方で文書化しなければなりません。
  • その機能は、 UNIX と Windows 上の CPython 2.6 と 2.7 、および UNIX 上の PyPy で完全に動作しなければなりません。ほとんどの Pylons プロジェクトパッケージは、今や Python 3 上で動作するか、または動作 することが期待されています; あなたがそのようなパッケージに取り組んでおり、 それが既に Python 3.2 上で動作するなら、あなたの変更の後でも Python 3.2 の下で動作し続けなければなりません。いくつかのパッケージは 明示的に Python 2.4 あるいは Python 2.5 サポートをリストしています; そのようなサポートが存在する場合、それを維持すべきです。ほとんどの Pylons プロジェクトパッケージの tox.ini は、どのバージョンの下で テストされるか示します。
  • その機能はどのような特別な永続化層 (ファイルシステム、 SQL など) にも依存 してはなりません。
  • その機能は不必要な依存性を加えてはなりません (もちろん「不必要な」 というのは主観的なものですが、新しい依存性は議論を要します)。

上記の必要条件は paster テンプレート依存性について緩められます。 paster テンプレートが特定のプラットフォーム上で動作しないインストール時 の依存性を持っている場合、 その (docs/ ディレクトリ内にある) ドキュメンテーションの中ではっきりと警告が書かれていなければなりません

ある機能を既存のパッケージに加えるべきか、それとも単独のパッケージと するのが相応しいかどうかを判断するために、遠慮なく開発者チームの誰かに 話しかけてください。

ドキュメンテーションカバレージ

あなたがバグを直し、そのバグが API または振る舞いの修正を必要とする場合、 その API または振る舞いを参照するパッケージ中のすべてのドキュメンテーション はバグフィックスを反映して変更しなければなりません。バグを修正する、または 機能を追加するのと同じコミットの中で行われるのが理想的です。

Change Log

機能追加とバグフィックスは、一般的なスタイルで CHANGES.txt ファイル に加えられなければなりません。 Changelog エントリは、暗号的でなく長文で 記述的であるべきです。他の開発者があなたの changelog エントリの意味を 理解できなければなりません。

テストカバレージ

コードベースは各コミットの後で 100% のテスト行カバレージを持って いなければなりません。 python setup.py nosetests --with-coverage によってカバレージをテストすることができます (nosecoverage パッケージが必要です)。

一貫したやり方でコードをテストすることは困難かもしれません。テストに 関する私たちのスタイル (「ドグマ(教義)」) を開発者が学習するのを助ける ため、テストに関する諸注意を 単体テストガイドライン に用意しています。

コーディングスタイル

すべての Python コードは PEP-8 スタイルガイドラインに 従ってください。空白に関するルールは緩められ、クラス間に2行の空行を 置くことは必須ではありません (そうすることはまったく問題ありませんが)。 特に 1行 80 カラムは必ず守ってください。

  • 単一行のインポート

    このようにしてください:

    1
    2
    import os
    import sys
    

    このように しないで ください:

    1
    import os, sys
    

    1行につき1つインポートすることは、パッチを読んだり差分をコミットする ことをより簡単にします。

    単一のパッケージから数多くの名前をインポートする必要がある場合は、次の 書式を使用してください:

    from thepackage import (
        foo,
        bar,
        baz,
        )
    
  • インポート順

    インポートはその起源の順で並べなければなりません。名前は以下の順で インポートすべきです:

    1. Python 標準ライブラリ
    2. サードパーティパッケージ
    3. 現在のパッケージの他のモジュール
  • ワイルドカードインポート

    あるパッケージからすべての名前をインポートしては なりません (例えば from package import * を使用しないでください)。必要なものだけを インポートしてください。ここで、単一行インポートも同様に適用されます。 別のパッケージからのそれぞれの名前は、別々の行でインポートしなければ なりません。

  • デフォルト引数として変更可能オブジェクトを使用しない

    Python は関数/メソッドのデフォルト引数をたった一度だけ解析するので、 それらをデフォルト引数として安全に使用できないということを忘れないで ください。

    このように しないで ください:

    1
    2
    3
    def somefunc(default={}):
        if default.get(...):
            ...
    

    これらのどちらかであれば構いません:

    1
    2
    def somefunc(default=None):
        default = default or {}
    
    1
    2
    3
    def somefunc(default=None):
        if default is None:
            default = {}
    
  • 人々がインポート時の副作用に依存せざるをえないようにすることは極めて 推奨されません。

    何らかのモジュールスコープのコードを実行するという単一の目的のためだけに モジュールやパッケージをインポートすることを誰かに要求するコードの作成は、 極めて推奨されません。コアの中で paster テンプレートにそのようなコードを 追加することだけは許されています。そうしたことは、他のフレームワークに よって必要とされる場合があります (例えば、 SQLAlchemy “declarative base” クラスが登録されるためにはインポートされる必要があります)。