This document is for an old version of Python that is no longer supported. You should upgrade and read the Dokumentasi Python untuk rilis stabil saat ini.

# 6. Modul-Modul

Jika Anda berhenti dari interpreter Python dan memasukkannya lagi, definisi yang Anda buat (fungsi dan variabel) akan hilang. Karena itu, jika Anda ingin menulis program yang agak lebih panjang, Anda lebih baik menggunakan editor teks untuk menyiapkan input bagi penerjemah dan menjalankannya dengan file itu sebagai input. Ini dikenal sebagai membuat script. Saat program Anda menjadi lebih panjang, Anda mungkin ingin membaginya menjadi beberapa file untuk pengelolaan yang lebih mudah. Anda mungkin juga ingin menggunakan fungsi praktis yang Anda tulis di beberapa program tanpa menyalin definisi ke setiap program.

Untuk mendukung ini, Python memiliki cara untuk meletakkan definisi dalam file dan menggunakannya dalam skrip atau dalam contoh interaktif dari interpreter. File seperti itu disebut module; definisi dari modul dapat imported ke modul lain atau ke modul main (kumpulan variabel yang Anda memiliki akses ke dalam skrip yang dieksekusi di tingkat atas dan dalam mode kalkulator).

Modul adalah file yang berisi definisi dan pernyataan Python. Nama berkas adalah nama modul dengan akhiran `.py` diakhirnya. Dalam sebuah modul, nama modul (sebagai string) tersedia sebagai nilai variabel global `__name__`. Misalnya, gunakan editor teks favorit Anda untuk membuat bernama bernama `fibo.py` di direktori saat ini dengan konten berikut

    # Fibonacci numbers module

    def fib(n):    # write Fibonacci series up to n
        a, b = 0, 1
        while b < n:
            print b,
            a, b = b, a+b

    def fib2(n):   # return Fibonacci series up to n
        result = []
        a, b = 0, 1
        while b < n:
            result.append(b)
            a, b = b, a+b
        return result

Sekarang masukkan interpreter Python dan impor modul ini dengan perintah berikut:

    >>> import fibo

Ini tidak memasukkan nama fungsi yang didefinisikan dalam `fibo` secara langsung dalam tabel simbol saat ini; itu hanya memasukkan nama modul `fibo` di sana. Menggunakan nama modul Anda dapat mengakses fungsi:

    >>> fibo.fib(1000)
    1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
    >>> fibo.fib2(100)
    [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
    >>> fibo.__name__
    'fibo'

Jika Anda sering ingin menggunakan suatu fungsi, Anda dapat menetapkannya ke nama lokal:

    >>> fib = fibo.fib
    >>> fib(500)
    1 1 2 3 5 8 13 21 34 55 89 144 233 377

## 6.1. Lebih lanjut tentang Modul

Modul dapat berisi pernyataan yang dapat dieksekusi serta definisi fungsi. Pernyataan ini dimaksudkan untuk menginisialisasi modul. Mereka dieksekusi hanya first kali nama modul ditemui dalam pernyataan impor. 1 (Mereka juga dijalankan jika file dieksekusi sebagai skrip.)

Setiap modul memiliki tabel simbol pribadi sendiri, yang digunakan sebagai tabel simbol global oleh semua fungsi yang didefinisikan dalam modul. Dengan demikian, penulis modul dapat menggunakan variabel global dalam modul tanpa khawatir tentang bentrokan tidak disengaja dengan variabel global pengguna. Di sisi lain, jika Anda tahu apa yang Anda lakukan, Anda dapat menyentuh variabel global modul dengan notasi yang sama yang digunakan untuk merujuk ke fungsinya, `modname.itemname`.

Modul dapat mengimpor modul lain. Biasanya, tetapi tidak diperlukan untuk menempatkan semua pernyataan `import` di awal modul (atau skrip, dalam hal ini). Nama-nama modul yang diimpor ditempatkan di tabel simbol global modul impor.

Ada varian dari pernyataan `import` yang mengimpor nama dari modul langsung ke tabel simbol modul impor. Sebagai contoh:

    >>> from fibo import fib, fib2
    >>> fib(500)
    1 1 2 3 5 8 13 21 34 55 89 144 233 377

Ini tidak memperkenalkan nama modul dari mana impor diambil dalam tabel simbol lokal (jadi dalam contoh, `fibo` tidak didefinisikan).

Bahkan ada varian untuk mengimpor semua nama yang didefinisikan oleh modul:

    >>> from fibo import *
    >>> fib(500)
    1 1 2 3 5 8 13 21 34 55 89 144 233 377

This imports all names except those beginning with an underscore (`_`).

Perhatikan bahwa secara umum praktik mengimpor `*` dari modul atau paket tidak disukai, karena sering menyebabkan kode yang kurang dapat dibaca. Namun, boleh saja menggunakannya untuk menghemat pengetikan di sesi interaktif.

If the module name is followed by `as`, then the name following `as` is bound directly to the imported module.

    >>> import fibo as fib
    >>> fib.fib(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Ini secara efektif mengimpor modul dengan cara yang sama dengan `import fibo` akan dilakukan, dengan satu-satunya perbedaan adalah sebagai `fib`.

Itu juga dapat digunakan ketika menggunakan `from` dengan efek yang sama:

    >>> from fibo import fib as fibonacci
    >>> fibonacci(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Catatan

For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the interpreter -- or, if it's just one module you want to test interactively, use `reload()`, e.g. `reload(modulename)`.

### 6.1.1. Mengoperasikan modul sebagai skrip

Ketika Anda mengoperasikan modul Python dengan

    python fibo.py <arguments>

kode dalam modul akan dieksekusi, sama seperti jika Anda mengimpornya, tetapi dengan `__name__` diatur ke `"__main__"`. Itu berarti bahwa dengan menambahkan kode ini di akhir modul Anda

    if __name__ == "__main__":
        import sys
        fib(int(sys.argv[1]))

Anda dapat membuat berkas dapat digunakan sebagai skrip dan juga modul yang dapat diimpor, karena kode yang mengurai parsing baris perintah hanya beroperasi jika modul dieksekusi sebagai berkas "main":

    $ python fibo.py 50
    1 1 2 3 5 8 13 21 34

Jika modul diimpor, kode ini tidak dioperasikan

    >>> import fibo
    >>>

Ini sering digunakan baik untuk menyediakan antarmuka pengguna yang nyaman ke modul, atau untuk tujuan pengujian (menjalankan modul sebagai skrip mengeksekusi rangkaian pengujian).

### 6.1.2. Jalur Pencarian Modul

Ketika sebuah modul bernama `spam` diimpor, interpreter pertama-tama mencari modul bawaan dengan nama itu. Jika tidak ditemukan, ia kemudian mencari berkas bernama `spam.py` dalam daftar direktori yang diberikan oleh variabel `sys.path`. `sys.path` diinisialisasi dari lokasi ini:

- the directory containing the input script (or the current directory).

- `PYTHONPATH` (daftar nama direktori, dengan sintaksis yang sama dengan variabel shell `PATH`).

- the installation-dependent default.

Setelah inisialisasi, program Python dapat memodifikasi: data :sys.path. Direktori yang berisi skrip yang dijalankan ditempatkan di awal jalur pencarian, di depan jalur pustaka standar. Ini berarti bahwa skrip dalam direktori itu akan dimuat bukan modul dengan nama yang sama di direktori pustaka. Ini adalah kesalahan kecuali penggantian memang diharapkan. Lihat bagian Modul Standar untuk informasi lebih lanjut.

### 6.1.3. Berkas Python "Compiled"

As an important speed-up of the start-up time for short programs that use a lot of standard modules, if a file called `spam.pyc` exists in the directory where `spam.py` is found, this is assumed to contain an already-"byte-compiled" version of the module `spam`. The modification time of the version of `spam.py` used to create `spam.pyc` is recorded in `spam.pyc`, and the `.pyc` file is ignored if these don't match.

Normally, you don't need to do anything to create the `spam.pyc` file. Whenever `spam.py` is successfully compiled, an attempt is made to write the compiled version to `spam.pyc`. It is not an error if this attempt fails; if for any reason the file is not written completely, the resulting `spam.pyc` file will be recognized as invalid and thus ignored later. The contents of the `spam.pyc` file are platform independent, so a Python module directory can be shared by machines of different architectures.

Beberapa tips untuk para ahli:

- When the Python interpreter is invoked with the `-O` flag, optimized code is generated and stored in `.pyo` files. The optimizer currently doesn't help much; it only removes `assert` statements. When `-O` is used, all bytecode is optimized; `.pyc` files are ignored and `.py` files are compiled to optimized bytecode.

- Passing two `-O` flags to the Python interpreter (`-OO`) will cause the bytecode compiler to perform optimizations that could in some rare cases result in malfunctioning programs. Currently only `__doc__` strings are removed from the bytecode, resulting in more compact `.pyo` files. Since some programs may rely on having these available, you should only use this option if you know what you're doing.

- A program doesn't run any faster when it is read from a `.pyc` or `.pyo` file than when it is read from a `.py` file; the only thing that's faster about `.pyc` or `.pyo` files is the speed with which they are loaded.

- When a script is run by giving its name on the command line, the bytecode for the script is never written to a `.pyc` or `.pyo` file. Thus, the startup time of a script may be reduced by moving most of its code to a module and having a small bootstrap script that imports that module. It is also possible to name a `.pyc` or `.pyo` file directly on the command line.

- It is possible to have a file called `spam.pyc` (or `spam.pyo` when `-O` is used) without a file `spam.py` for the same module. This can be used to distribute a library of Python code in a form that is moderately hard to reverse engineer.

- The module `compileall` can create `.pyc` files (or `.pyo` files when `-O` is used) for all modules in a directory.

## 6.2. Modul Standar

Python dilengkapi dengan pustaka modul standar, yang dijelaskan dalam dokumen terpisah, Referensi Pustaka Python ("Library Reference" selanjutnya). Beberapa modul dibangun ke dalam interpreter; ini menyediakan akses ke operasi yang bukan bagian dari inti bahasa tetapi tetap dibangun, baik untuk efisiensi atau untuk menyediakan akses ke sistem operasi primitif seperti pemanggilan sistem. Himpunan modul tersebut adalah opsi konfigurasi yang juga tergantung pada platform yang mendasarinya. Sebagai contoh, modul `winreg` hanya disediakan pada sistem Windows. Satu modul tertentu patut mendapat perhatian: `sys`, yang dibangun ke dalam setiap interpreter Python. Variabel `sys.ps1` dan `sys.ps2` menentukan string yang digunakan sebagai prompt primer dan sekunder

    >>> import sys
    >>> sys.ps1
    '>>> '
    >>> sys.ps2
    '... '
    >>> sys.ps1 = 'C> '
    C> print 'Yuck!'
    Yuck!
    C>

Kedua variabel ini hanya ditentukan jika interpreter dalam mode interaktif.

Variabel `sys.path` adalah daftar string yang menentukan jalur pencarian interpreter untuk modul. Ini diinisialisasi ke jalur default yang diambil dari variabel lingkungan `PYTHONPATH`, atau dari bawaan bawaan jika `PYTHONPATH` tidak disetel. Anda dapat memodifikasinya menggunakan operasi standar untuk list:

    >>> import sys
    >>> sys.path.append('/ufs/guido/lib/python')

## 6.3. Fungsi `dir()`

Fungsi bawaan `dir()` digunakan untuk mencari tahu nama-nama yang ditentukan oleh modul. Ia mengembalikan list string yang diurutkan:

    >>> import fibo, sys
    >>> dir(fibo)
    ['__name__', 'fib', 'fib2']
    >>> dir(sys)
    ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__',
     '__stderr__', '__stdin__', '__stdout__', '_clear_type_cache',
     '_current_frames', '_getframe', '_mercurial', 'api_version', 'argv',
     'builtin_module_names', 'byteorder', 'call_tracing', 'callstats',
     'copyright', 'displayhook', 'dont_write_bytecode', 'exc_clear', 'exc_info',
     'exc_traceback', 'exc_type', 'exc_value', 'excepthook', 'exec_prefix',
     'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
     'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
     'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
     'getrefcount', 'getsizeof', 'gettotalrefcount', 'gettrace', 'hexversion',
     'long_info', 'maxint', 'maxsize', 'maxunicode', 'meta_path', 'modules',
     'path', 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
     'py3kwarning', 'setcheckinterval', 'setdlopenflags', 'setprofile',
     'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', 'subversion',
     'version', 'version_info', 'warnoptions']

Tanpa argumen, `dir()` mencantumkan nama yang telah Anda tentukan saat ini:

    >>> a = [1, 2, 3, 4, 5]
    >>> import fibo
    >>> fib = fibo.fib
    >>> dir()
    ['__builtins__', '__name__', '__package__', 'a', 'fib', 'fibo', 'sys']

Perhatikan bahwa ini mencantumkan semua jenis nama: variabel, modul, fungsi, dll.

`dir()` does not list the names of built-in functions and variables. If you want a list of those, they are defined in the standard module `__builtin__`:

    >>> import __builtin__
    >>> dir(__builtin__)
    ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
     'BufferError', 'BytesWarning', 'DeprecationWarning', 'EOFError',
     'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FloatingPointError',
     'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning',
     'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
     'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
     'NotImplementedError', 'OSError', 'OverflowError',
     'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
     'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError',
     'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
     'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
     'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
     'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning',
     'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
     '__name__', '__package__', 'abs', 'all', 'any', 'apply', 'basestring',
     'bin', 'bool', 'buffer', 'bytearray', 'bytes', 'callable', 'chr',
     'classmethod', 'cmp', 'coerce', 'compile', 'complex', 'copyright',
     'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval',
     'execfile', 'exit', 'file', 'filter', 'float', 'format', 'frozenset',
     'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input',
     'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len', 'license',
     'list', 'locals', 'long', 'map', 'max', 'memoryview', 'min', 'next',
     'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit',
     'range', 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round',
     'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
     'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']

## 6.4. Paket

Paket adalah cara penataan namespace modul Python dengan menggunakan "dotted module names". Sebagai contoh, nama modul `A.B` menetapkan submodule bernama `B` dalam sebuah paket bernama `A`. Sama seperti penggunaan modul menyelamatkan penulis modul yang berbeda dari harus khawatir tentang nama variabel global masing-masing, penggunaan nama modul bertitik menyelamatkan penulis paket multi-modul seperti NumPy atau Pillow dari harus khawatir tentang nama modul masing-masing .

Misalkan Anda ingin merancang koleksi modul ("paket") untuk penanganan berkas suara dan data suara yang seragam. Ada banyak format berkas suara yang berbeda (biasanya dikenali oleh ekstensi mereka, misalnya: `.wav`, `.aiff`, `.au`), jadi Anda mungkin perlu membuat dan memelihara koleksi modul yang terus bertambah untuk konversi antara berbagai format file. Ada juga banyak operasi berbeda yang mungkin ingin Anda lakukan pada data suara (seperti mencampur, menambahkan gema, menerapkan fungsi equalizer, menciptakan efek stereo buatan), jadi selain itu Anda akan menulis aliran modul tanpa henti untuk melakukan operasi ini. Berikut adalah struktur yang mungkin untuk paket Anda (dinyatakan dalam hierarki sistem file):

    sound/                          Top-level package
          __init__.py               Initialize the sound package
          formats/                  Subpackage for file format conversions
                  __init__.py
                  wavread.py
                  wavwrite.py
                  aiffread.py
                  aiffwrite.py
                  auread.py
                  auwrite.py
                  ...
          effects/                  Subpackage for sound effects
                  __init__.py
                  echo.py
                  surround.py
                  reverse.py
                  ...
          filters/                  Subpackage for filters
                  __init__.py
                  equalizer.py
                  vocoder.py
                  karaoke.py
                  ...

Saat mengimpor paket, Python mencari melalui direktori pada `sys.path` mencari subdirektori paket.

The `__init__.py` files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such as `string`, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case, `__init__.py` can just be an empty file, but it can also execute initialization code for the package or set the `__all__` variable, described later.

Pengguna paket dapat mengimpor modul individual dari paket, misalnya:

    import sound.effects.echo

Ini memuat submodule `sound.effects.echo`. Itu harus dirujuk dengan nama lengkapnya.

    sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

Cara alternatif mengimpor submodule adalah:

    from sound.effects import echo

Ini juga memuat submodul :mod: echo, dan membuatnya tersedia tanpa awalan paketnya, sehingga dapat digunakan sebagai berikut:

    echo.echofilter(input, output, delay=0.7, atten=4)

Namun variasi lain adalah mengimpor fungsi atau variabel yang diinginkan secara langsung:

    from sound.effects.echo import echofilter

Sekali lagi, ini memuat submodul `echo`, tetapi ini membuat fungsinya `echofilter()` langsung tersedia:

    echofilter(input, output, delay=0.7, atten=4)

Perhatikan bahwa ketika menggunakan `from package import item`, item tersebut dapat berupa submodul (atau subpaket) dari paket, atau beberapa nama lain yang ditentukan dalam paket, seperti fungsi, kelas atau variabel. Pernyataan `import` pertama menguji apakah item tersebut didefinisikan dalam paket; jika tidak, ini dianggap sebagai modul dan mencoba memuatnya. Jika gagal menemukannya, pengecualian `ImportError` dimunculkan.

Sebaliknya, ketika menggunakan sintaksis seperti `import item.subitem.subsubitem`, setiap item kecuali yang terakhir harus berupa paket; item terakhir dapat berupa modul atau paket tetapi tidak bisa berupa kelas atau fungsi atau variabel yang didefinisikan dalam item sebelumnya.

### 6.4.1. Mengimpor * Dari Paket

Sekarang apa yang terjadi ketika pengguna menulis `from sound.effects import *`? Idealnya, orang akan berharap bahwa ini entah bagaimana keluar ke sistem file, menemukan submodul mana yang ada dalam paket, dan mengimpor semuanya. Ini bisa memakan waktu lama dan mengimpor submodul mungkin memiliki efek samping yang tidak diinginkan yang seharusnya hanya terjadi ketika submodul diimpor secara eksplisit.

Satu-satunya solusi adalah bagi pembuat paket untuk memberikan indeks paket secara eksplisit. Pernyataan `import` menggunakan konvensi berikut: jika suatu paket punya kode `__init __.py` yang mendefinisikan daftar bernama `__all__`, itu diambil sebagai daftar nama modul yang harus diimpor ketika `from package import *` ditemukan. Terserah pembuat paket untuk tetap memperbarui daftar ini ketika versi baru dari paket dirilis. Pembuat paket juga dapat memutuskan untuk tidak mendukungnya, jika mereka tidak melihat penggunaan untuk mengimpor * dari paket mereka. Sebagai contoh, berkas `sound/effects/__init__.py` dapat berisi kode berikut:

    __all__ = ["echo", "surround", "reverse"]

Ini berarti bahwa `from sound.effects import *` akan mengimpor tiga submodul bernama dari paket `sound`.

Jika `__all__` tidak didefinisikan, pernyataan `from sound.effects import *` tidak impor semua submodul dari paket `sound.effects` ke namespace saat ini; itu hanya memastikan bahwa paket `sound.effects` telah diimpor (mungkin menjalankan kode inisialisasi apa pun di `__init__.py`) dan kemudian mengimpor nama apa pun yang didefinisikan dalam paket. Ini termasuk semua nama yang didefinisikan (dan submodul yang dimuat secara eksplisit) oleh `__init__.py`. Itu juga termasuk semua submodul dari paket yang secara eksplisit dimuat oleh sebelumnya pernyataan `import`. Pertimbangkan kode ini

    import sound.effects.echo
    import sound.effects.surround
    from sound.effects import *

Dalam contoh ini, modul `echo` dan `surround` diimpor dalam namespace saat ini karena mereka didefinisikan dalam paket `sound.effects` ketika paket `from...import` Pernyataan dieksekusi. (Ini juga berfungsi ketika `__all__` didefinisikan.)

Meskipun modul-modul tertentu dirancang hanya untuk mengekspor nama-nama yang mengikuti pola tertentu ketika Anda menggunakan `import *`, itu masih dianggap praktik buruk dalam lingkungan kode produksi production.

Ingat, tidak ada yang salah dengan menggunakan `from package import specific_submodule`! Sebenarnya, ini adalah notasi yang disarankan kecuali modul impor perlu menggunakan submodul dengan nama yang sama dari paket yang berbeda.

### 6.4.2. Referensi Intra-paket

The submodules often need to refer to each other. For example, the `surround` module might use the `echo` module. In fact, such references are so common that the `import` statement first looks in the containing package before looking in the standard module search path. Thus, the `surround` module can simply use `import echo` or `from echo import echofilter`. If the imported module is not found in the current package (the package of which the current module is a submodule), the `import` statement looks for a top-level module with the given name.

Ketika paket disusun menjadi subpaket (seperti pada paket `sound` pada contoh), Anda dapat menggunakan impor absolut untuk merujuk pada submodul paket saudara kandung. Misalnya, jika modul `sound.filters.vocoder` perlu menggunakan modul `echo` dalam paket `sound.effects`, ia dapat menggunakan `from sound.effects import echo`.

Starting with Python 2.5, in addition to the implicit relative imports described above, you can write explicit relative imports with the `from module import name` form of import statement. These explicit relative imports use leading dots to indicate the current and parent packages involved in the relative import. From the `surround` module for example, you might use:

    from . import echo
    from .. import formats
    from ..filters import equalizer

Note that both explicit and implicit relative imports are based on the name of the current module. Since the name of the main module is always `"__main__"`, modules intended for use as the main module of a Python application should always use absolute imports.

### 6.4.3. Paket di Beberapa Direktori

Paket mendukung satu atribut khusus lagi, `__path__`. Ini diinisialisasi menjadi daftar yang berisi nama direktori yang menyimpan file paket: __init__.py sebelum kode dalam file tersebut dieksekusi. Variabel ini dapat dimodifikasi; hal itu memengaruhi pencarian modul dan subpackage di masa depan yang terkandung dalam paket.

Meskipun fitur ini tidak sering dibutuhkan, fitur ini dapat digunakan untuk memperluas rangkaian modul yang ditemukan dalam suatu paket.

Catatan kaki

1

  Bahkan definisi fungsi juga 'statements' yang 'executed'; eksekusi dari definisi fungsi level-modul memasukkan nama fungsi di tabel simbol global modul.