"linecache" --- Random access to text lines
*******************************************

**ソースコード:** Lib/linecache.py

======================================================================

"linecache" モジュールは、キャッシュ (一つのファイルから何行も読んでお
くのが一般的です) を使って、内部で最適化を図りつつ、Python ソースファ
イルの任意の行を取得するのを可能にします。 "traceback" モジュールは、
整形されたトレースバックにソースコードを含めるためにこのモジュールを利
用しています。

"tokenize.open()" 関数は、ファイルを開くために使用されます。この関数は
、 "tokenize.detect_encoding()" を使用してファイルのエンコーディングを
取得します。エンコーディングトークンが存在しない場合、デフォルトの
UTF-8 になります。

"linecache" モジュールでは次の関数が定義されています:

linecache.getline(filename, lineno, module_globals=None)

   *filename* という名前のファイルから *lineno* 行目を取得します。この
   関数は決して例外を発生させません --- エラーの際には "''" を返します
   (行末の改行文字は、見つかった行に含まれます)。

   *filename* という名前のファイルが見付からなかった場合、この関数は最
   初に *module_globals* にある **PEP 302** "__loader__" を確認します
   。 ローダーが存在していて、 "get_source" メソッドが実装されていた場
   合、ソースコードの行を決定します ("get_source()" が "None" を返した
   場合は、 "''" が返ります)。 最後に、 *filename* が相対ファイル名だ
   った場合、モジュール検索パス "sys.path" のエントリからの相対パスを
   探します。

linecache.clearcache()

   キャッシュをクリアします。それまでに "getline()" を使って読み込んだ
   ファイルの行が必要でなくなったら、この関数を使ってください。

linecache.checkcache(filename=None)

   キャッシュが有効かどうかを確認します。キャッシュしたファイルがディ
   スク上で変更された可能性があり、更新後のバージョンが必要な場合にこ
   の関数を使用します。 *filename* が与えられない場合、全てのキャッシ
   ュエントリを確認します。

linecache.lazycache(filename, module_globals)

   後々の呼び出しで *module_globals* が "None" となっていても、ファイ
   ルの形式でないモジュールの行を後から "getline()" で取得するのに十分
   な詳細を把握しておきます。この関数により、モジュールの globals を無
   限に持ち運ぶ必要無しに、実際に必要な行まで I/O を行う必要がなくなり
   ます。

   バージョン 3.5 で追加.

以下はプログラム例です:

   >>> import linecache
   >>> linecache.getline(linecache.__file__, 8)
   'import sys\n'
