# `gzip` — Support for gzip files

Вихідний код: Lib/gzip.py

Цей модуль надає простий інтерфейс для стиснення та розпакування файлів, як це робили б програми GNU gzip і gunzip.

This is an optional module. If it is missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see Requirements for optional modules.

Стиснення даних забезпечується модулем `zlib`.

The `gzip` module provides the `GzipFile` class, as well as the `open()`, `compress()` and `decompress()` convenience functions. The `GzipFile` class reads and writes gzip-format files, automatically compressing or decompressing the data so that it looks like an ordinary file object.

Зауважте, що додаткові формати файлів, які можна розпакувати програмами gzip і gunzip, наприклад ті, створені compress і pack, не підтримуються цим модуль.

Модуль визначає такі елементи:

gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None, *, mtime=None)

  Відкрийте файл, стиснутий gzip, у двійковому або текстовому режимі, повертаючи file object.

  Аргументом filename може бути фактичне ім’я файлу (об’єкт `str` або `bytes`) або наявний файловий об’єкт для читання або запису.

  Аргумент mode може бути будь-яким із `'r'`, `'rb'`, `'a'`, `'ab'`, `'w'`, `'wb'`, `'x'` або `'xb'` для бінарного режиму або `'rt'`, `'at'`, `'wt'` або `'xt''` для текстового режиму. Типовим є `'rb'`.

  Аргумент compresslevel є цілим числом від 0 до 9, як і для конструктора `GzipFile`.

  The keyword-only argument mtime represents a Unix timestamp.

  For binary mode, this function is equivalent to the `GzipFile` constructor: `GzipFile(filename, mode, compresslevel, mtime=mtime)`. In this case, the encoding, errors and newline arguments must not be provided.

  Для текстового режиму створюється об’єкт `GzipFile`, який загортається в екземпляр `io.TextIOWrapper` із вказаним кодуванням, поведінкою обробки помилок і закінченнями рядків.

  Змінено в версії 3.3: Додано підтримку того, що ім’я файлу є об’єктом файлу, підтримується текстовий режим, а також аргументи кодування, помилки та новий рядок.

  Змінено в версії 3.4: Додано підтримку режимів `'x'`, `'xb'` і `'xt'`.

  Змінено в версії 3.6: Приймає path-like object.

  Змінено в версії 3.15: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

  Змінено в версії 3.16.0a0 (unreleased): Added keyword-only argument mtime which is passed to the class constructor of `GzipFile`.

exception gzip.BadGzipFile

  An exception raised for invalid gzip files. It inherits from `OSError`. `EOFError` and `zlib.error` can also be raised for invalid gzip files.

  Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)

  Constructor for the `GzipFile` class, which simulates most of the methods of a file object, with the exception of the `truncate()` method. At least one of fileobj and filename must be given a non-trivial value.

  Новий екземпляр класу базується на fileobj, який може бути звичайним файлом, об’єктом `io.BytesIO` або будь-яким іншим об’єктом, який імітує файл. За замовчуванням встановлено `None`, у цьому випадку ім’я_файлу відкривається, щоб надати об’єкт файлу.

  Якщо fileobj не є `None`, аргумент filename використовується лише для включення в заголовок файлу gzip, який може містити оригінальну назву нестисненого файлу. За замовчуванням ім’я файлу fileobj, якщо воно помітне; інакше за замовчуванням буде порожній рядок, і в цьому випадку оригінальна назва файлу не буде включена в заголовок.

  Аргумент mode може бути будь-яким із `'r'`, `'rb'`, `'a'`, `'ab'`, `'w'`, `'wb'`, `'x'` або `'xb'`, залежно від того, чи буде файл читатися чи записуватися. Типовим є режим fileobj, якщо він помітний; інакше за замовчуванням буде `'rb'`. У майбутніх випусках Python режим fileobj не використовуватиметься. Краще завжди вказувати режим для запису.

  Зауважте, що файл завжди відкривається у двійковому режимі. Щоб відкрити стислий файл у текстовому режимі, використовуйте `open()` (або загорніть свій `GzipFile` у `io.TextIOWrapper`).

  Аргумент compresslevel є цілим числом від `0` до `9`, що контролює рівень стиснення; `1` є найшвидшим і забезпечує найменше стиснення, а `9` є найповільнішим і забезпечує найбільше стиснення. `0` не стискає. Типовим значенням є `9`.

  The optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. Set mtime to `0` to generate a compressed stream that does not depend on creation time. If mtime is omitted or `None`, the current time is used; however, if the current time is outside the range 00:00:00 UTC, January 1, 1970 through 06:28:15 UTC, February 7, 2106, or explicitly passed mtime argument is outside the range `0` to `2**32-1`, then the value `0` is used instead.

  See below for the `mtime` attribute that is set when decompressing.

  Calling a `GzipFile` object’s `close()` method does not close fileobj, since you might wish to append more material after the compressed data. This also allows you to pass an `io.BytesIO` object opened for writing as fileobj, and retrieve the resulting memory buffer using the `io.BytesIO` object’s `getvalue()` method.

  `GzipFile` supports the `io.BufferedIOBase` interface, including iteration and the `with` statement. Only the `truncate()` method isn’t implemented.

  `GzipFile` також надає наступний метод і атрибут:

  peek(n)

    Read n uncompressed bytes without advancing the file position. The number of bytes returned may be more or less than requested.

    Примітка

    Хоча виклик `peek()` не змінює позицію файлу `GzipFile`, він може змінити позицію основного файлового об’єкта (наприклад, якщо `GzipFile` було створено за допомогою fileobj параметр).

    Added in version 3.2.

  mode

    `'rb'` for reading and `'wb'` for writing.

    Змінено в версії 3.13: In previous versions it was an integer `1` or `2`.

  mtime

    When decompressing, this attribute is set to the last timestamp in the most recently read header. It is an integer, holding the number of seconds since the Unix epoch (00:00:00 UTC, January 1, 1970). The initial value before reading any headers is `None`.

  name

    The path to the gzip file on disk, as a `str` or `bytes`. Equivalent to the output of `os.fspath()` on the original input path, with no other normalization, resolution or expansion.

  Змінено в версії 3.1: Додано підтримку оператора `with` разом з аргументом конструктора mtime і атрибутом `mtime`.

  Змінено в версії 3.2: Було додано підтримку файлів із нульовою підкладкою та файлів, які неможливо знайти.

  Змінено в версії 3.3: Метод `io.BufferedIOBase.read1()` тепер реалізовано.

  Змінено в версії 3.4: Додано підтримку режимів `'x'` і `'xb'`.

  Змінено в версії 3.5: Додано підтримку запису довільних байт-подібних об’єктів. Метод `read()` тепер приймає аргумент `None`.

  Змінено в версії 3.6: Приймає path-like object.

  Застаріло починаючи з версії 3.9: Відкриття `GzipFile` для запису без вказівки аргументу mode застаріло.

  Змінено в версії 3.12: Remove the `filename` attribute, use the `name` attribute instead.

  Змінено в версії 3.15: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

gzip.compress(data, compresslevel=6, *, mtime=0)

  Compress the data, returning a `bytes` object containing the compressed data. compresslevel and mtime have the same meaning as in the `GzipFile` constructor above, but mtime defaults to 0 for reproducible output.

  Added in version 3.2.

  Змінено в версії 3.8: Додано параметр mtime для відтворюваного виведення.

  Змінено в версії 3.11: Speed is improved by compressing all data at once instead of in a streamed fashion. Calls with mtime set to `0` are delegated to `zlib.compress()` for better speed. In this situation the output may contain a gzip header «OS» byte value other than 255 «unknown» as supplied by the underlying zlib implementation.

  Змінено в версії 3.13: The gzip header OS byte is guaranteed to be set to 255 when this function is used as was the case in 3.10 and earlier.

  Змінено в версії 3.14: The mtime parameter now defaults to 0 for reproducible output. For the previous behaviour of using the current time, pass `None` to mtime.

  Змінено в версії 3.15: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

gzip.decompress(data)

  Decompress the data, returning a `bytes` object containing the uncompressed data. This function is capable of decompressing multi-member gzip data (multiple gzip blocks concatenated together). When the data is certain to contain only one member the `zlib.decompress()` function with wbits set to 31 is faster.

  Added in version 3.2.

  Змінено в версії 3.11: Speed is improved by decompressing members at once in memory instead of in a streamed fashion.

## Приклади вживання

Приклад читання стисненого файлу:

    import gzip
    with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
        file_content = f.read()

Приклад створення стисненого файлу GZIP:

    import gzip
    content = b"Lots of content here"
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
        f.write(content)

Приклад того, як GZIP стиснути існуючий файл:

    import gzip
    import shutil
    with open('/home/joe/file.txt', 'rb') as f_in:
        with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
            shutil.copyfileobj(f_in, f_out)

Приклад того, як GZIP стиснути двійковий рядок:

    import gzip
    s_in = b"Lots of content here"
    s_out = gzip.compress(s_in)

Дивись також

Модуль `zlib`

  Базовий модуль стиснення даних, необхідний для підтримки формату файлу gzip.

In case gzip (de)compression is a bottleneck, the python-isal package speeds up (de)compression with a mostly compatible API.

## Command-line interface

The `gzip` module provides a simple command line interface to compress or decompress files.

Once executed the `gzip` module keeps the input file(s).

Змінено в версії 3.8: Додайте новий інтерфейс командного рядка з використанням. За замовчуванням, коли ви будете виконувати CLI, рівень стиснення за замовчуванням становить 6.

### Command-line options

file

  If file is not specified, read from `sys.stdin`.

--fast

  Вказує найшвидший метод стиснення (з меншим стисненням).

--best

  Вказує найповільніший метод стиснення (найкраще стиснення).

-d, --decompress

  Розпакуйте вказаний файл.

-h, --help

  Показати довідкове повідомлення.