pyhwp

https://pyhwp.readthedocs.io/en/latest/
Admin
pyhwp is a HWP Document Format v5 parser and processor that analyzes and extracts internal streams...
Tokens:11,363
Snippets:117
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install pyhwp for user

Source: https://pyhwp.readthedocs.io/en/latest/intro.html

Use this command to install pyhwp into the user's home directory. This is an alternative to virtual environment installation.

```bash
pip install --user --pre pyhwp  # Install pyhwp into user's home directory
```

--------------------------------

### Install lxml for pyhwp

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Install the lxml library for HWPv5 document processing. Use `--user` for user-specific installation or without it for virtual environments.

```bash
pip install --user lxml # install to user directory
```

```bash
pip install lxml        # install with virtualenv
```

--------------------------------

### Verify installation and run tests

Source: https://pyhwp.readthedocs.io/en/latest/hacking/setup-env.html

Check that hwp5proc is accessible and execute the test suite.

```bash
$ hwp5proc --help
```

```bash
$ tox
```

--------------------------------

### Unpacking HWP Files with hwp5proc unpack

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Examples show how to unpack an HWP file to the current directory or a specified directory, and how to unpack with virtual streams and view the content of a specific unpacked file.

```bash
$ hwp5proc unpack samples/sample-5017.hwp
$ ls sample-5017
```

```bash
$ hwp5proc unpack --vstreams samples/sample-5017.hwp
$ cat sample-5017/PrvText.utf8
```

--------------------------------

### Install xsltproc and xmllint for pyhwp

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Install the xsltproc and libxml2-utils packages on Debian/Ubuntu systems for HWPv5 document conversion. These tools are required for XSLT processing.

```bash
sudo apt-get install xsltproc libxml2-utils  # Debian/Ubuntu
```

--------------------------------

### Install pyhwp into a virtualenv

Source: https://pyhwp.readthedocs.io/en/latest/intro.html

Use this command to install pyhwp into a virtual environment. Ensure you have virtualenv installed.

```bash
virtualenv pyhwp
pyhwp/bin/pip install --pre pyhwp  # Install pyhwp into a virtualenv directory
```

--------------------------------

### Extracting and Processing HWP Streams with hwp5proc cat

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Examples demonstrate extracting streams like BinData/BIN0002.jpg and PrvText using hwp5proc cat, with options for virtual streams and character encoding conversion.

```bash
$ hwp5proc cat samples/sample-5017.hwp BinData/BIN0002.jpg | file -
```

```bash
$ hwp5proc cat samples/sample-5017.hwp BinData/BIN0002.jpg > BIN0002.jpg
```

```bash
$ hwp5proc cat samples/sample-5017.hwp PrvText | iconv -f utf-16le -t utf-8
```

```bash
$ hwp5proc cat --vstreams samples/sample-5017.hwp PrvText.utf8
```

```bash
$ hwp5proc cat --vstreams samples/sample-5017.hwp FileHeader.txt
```

```text
ccl: 0
cert_drm: 0
cert_encrypted: 0
cert_signature_extra: 0
cert_signed: 0
compressed: 1
distributable: 0
drm: 0
history: 0
password: 0
script: 0
signature: HWP Document File
version: 5.0.1.7
xmltemplate_storage: 0
```

--------------------------------

### JSONEncoder Default Implementation Example

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

This example shows how to implement the `default` method in a subclass of `JSONEncoder` to support serializing arbitrary iterators. It attempts to iterate over the object and returns a list if successful, otherwise it calls the base class implementation.

```python
def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
```

--------------------------------

### Convert Generator to File-like Reader

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Creates a file-like reader object from a string generator. Useful for reading data in chunks from a generator. The example demonstrates reading a specific number of bytes and then the remainder.

```python
f = GeneratorReader(gen())
assert ‘hell’ == f.read(4)
assert ‘oworld’ == f.read()
```

--------------------------------

### Iterate storage leaf nodes

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Iterates through every leaf node in the storage. The `basepath` parameter can be used to specify a starting path within the storage.

```python
hwp5.storage.iter_storage_leafs(stg, basepath='')
```

--------------------------------

### Convert Generator to Text Reader

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Creates a file-like reader object from a text generator. Similar to GeneratorReader but for text data. The example shows reading a specific number of characters and then the rest of the string.

```python
f = GeneratorTextReader(gen())
assert ‘hell’ == f.read(4)
assert ‘oworld’ == f.read()
```

--------------------------------

### Initialize the development environment

Source: https://pyhwp.readthedocs.io/en/latest/hacking/setup-env.html

Bootstrap the environment and activate the virtual environment.

```bash
$ make bootstrap
$ . bin/activate
```

--------------------------------

### Initialize Hwp5File with storage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes an Hwp5File object with a given storage instance. The storage can be an OleFileIO instance or a filename.

```python
Hwp5File(stg)
```

--------------------------------

### Initialize Hwp5FileBase with storage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes the base class for Hwp5File. It checks the basic validity of the HWP format v5 and provides access to the file header. Requires an instance of storage, OleFileIO, or a filename.

```python
Hwp5FileBase(stg)
```

--------------------------------

### Initialize Hwp5File for binary model

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes an Hwp5File object for processing the binary model.

```python
hwp5.binmodel.Hwp5File(stg)
```

--------------------------------

### Development and Testing Workflow

Source: https://pyhwp.readthedocs.io/en/latest/hacking/hack-n-test.html

Commands for building the environment, modifying source code, and executing tests.

```bash
$ bin/buildout

(...)

$ vim pyhwp/hwp5/proc/__init__.py

(HACK HACK HACK)

$ bin/test-core

$ bin/hwp5proc ...

$ bin/tox
```

--------------------------------

### summaryinfo Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Prints the summary information of HWPv5 files.

```APIDOC
## summaryinfo

Print summary informations of .hwp files.
Print the summary information of <hwp5file>.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze
```

--------------------------------

### ls Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Lists streams within HWPv5 files.

```APIDOC
## ls

List streams in .hwp files.
List streams in the <hwp5file>.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze

### Named Arguments

- **--vstreams** (boolean) - Optional - Process with virtual streams (i.e. parsed/converted form of real streams). Default: False
- **--ole** (boolean) - Optional - Treat <hwp5file> as an OLE Compound File. As a result, some streams will be presented as-is. (i.e. not decompressed). Default: False
```

--------------------------------

### version Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Prints the file format version of HWPv5 files.

```APIDOC
## version

Print the file format version of .hwp files.
Print the file format version of <hwp5file>.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze
```

--------------------------------

### Clone the pyhwp repository

Source: https://pyhwp.readthedocs.io/en/latest/hacking/setup-env.html

Use git to download the source code from the official repository.

```bash
$ git clone https://github.com/mete0r/pyhwp.git
```

--------------------------------

### Initialize Hwp5File for XML model

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes an Hwp5File object for processing the XML model.

```python
hwp5.xmlmodel.Hwp5File(stg)
```

--------------------------------

### hwp5html Usage

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Command-line usage for the hwp5html converter, which converts HWPv5 files to HTML format. Specify input file and optional arguments for output format.

```bash
usage: hwp5html [-h] [--version] [--loglevel LOGLEVEL] [--logfile LOGFILE]
                [--output OUTPUT] [--css | --html]
                <hwp5file>

```

--------------------------------

### hwp5txt Usage

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Command-line usage for the hwp5txt converter, which converts HWPv5 files to plain text format. Specify input file and optional output file.

```bash
usage: hwp5txt [-h] [--version] [--loglevel LOGLEVEL] [--logfile LOGFILE]
               [--output OUTPUT]
               <hwp5file>

```

--------------------------------

### hwp5proc summaryinfo Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to print summary information of HWP files. It requires the path to the HWP file as a positional argument.

```bash
usage: hwp5proc summaryinfo [-h] <hwp5file>
```

--------------------------------

### Initialize Hwp5File for record stream

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes an Hwp5File object specifically for the 'rec' layer of the record stream.

```python
hwp5.recordstream.Hwp5File(stg)
```

--------------------------------

### header Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Prints the file header of HWPv5 files.

```APIDOC
## header

Print file headers of .hwp files.
Print the file header of <hwp5file>.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze
```

--------------------------------

### hwp5proc version Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to print the file format version of HWP files. It requires the path to the HWP file as a positional argument.

```bash
usage: hwp5proc version [-h] <hwp5file>
```

--------------------------------

### hwp5.importhelper Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Helper functions for importing HWP data.

```APIDOC
## hwp5.importhelper

### Functions

- **pkg_resources_filename()**: Retrieves a filename using pkg_resources.
- **pkg_resources_filename_fallback()**: Fallback for retrieving filenames with pkg_resources.
```

--------------------------------

### hwp5.storage.unpack

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Unpacks an HWP storage container into a specified directory.

```APIDOC
## FUNCTION hwp5.storage.unpack

### Description
Unpack a storage into an output directory.

### Parameters
#### Path Parameters
- **stg** (Storage) - Required - An instance of Storage.
- **outbase** (string) - Required - Path to a directory in the filesystem (should not end with '/').
```

--------------------------------

### unpack Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Extracts internal streams from HWPv5 files into a specified directory.

```APIDOC
## unpack

Extract out internal streams of .hwp files into a directory.
Extract out streams in the specified <hwp5file> to a directory.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze
- **out-directory** (string) - Optional - Output directory

### Named Arguments

- **--vstreams** (boolean) - Optional - Process with virtual streams (i.e. parsed/converted form of real streams). Default: False
- **--ole** (boolean) - Optional - Treat <hwp5file> as an OLE Compound File. As a result, some streams will be presented as-is. (i.e. not decompressed). Default: False

### Request Example

```bash
hwp5proc unpack samples/sample-5017.hwp
ls sample-5017
```
```

--------------------------------

### Find HWP Records with Predicates using hwp5proc

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use the 'find' subcommand to locate HWP record models based on specified criteria such as model name, HWPTAG, or incomplete parsing. Results can be formatted or dumped.

```bash
$ hwp5proc find --model=Paragraph samples/*.hwp
$ hwp5proc find --tag=HWPTAG_PARA_TEXT samples/*.hwp
$ hwp5proc find --tag=66 samples/*.hwp
```

```bash
$ hwp5proc find --tag=HWPTAG_LIST_HEADER --incomplete --dump samples/*.hwp
```

--------------------------------

### hwp5proc Main Usage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

This is the main usage string for the hwp5proc command-line tool. It outlines the available subcommands for HWP file processing.

```bash
usage: hwp5proc [-h] [--loglevel LOGLEVEL] [--logfile LOGFILE]
                {version,header,summaryinfo,ls,cat,unpack,records,models,find,xml,rawunz,diststream}
                ...
```

--------------------------------

### Run rawunz command

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Displays the usage information for the rawunz subcommand.

```bash
usage: hwp5proc rawunz [-h]
```

--------------------------------

### Transform HWP to XML with hwp5proc

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

The 'xml' subcommand converts HWP files into XML format. It supports options for embedding binary data and controlling XML declaration output.

```bash
$ hwp5proc xml samples/sample-5017.hwp > sample-5017.xml
$ xmllint --format sample-5017.xml
```

```bash
$ hwp5proc xml --embedbin samples/sample-5017.hwp > sample-5017.xml
$ xmllint --format sample-5017.xml
```

--------------------------------

### hwp5proc models

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Prints parsed binary models of HWP file record streams. Supports various output formats and filtering options.

```APIDOC
## hwp5proc models

### Description
Prints parsed binary models of HWP file record streams. Supports various output formats and filtering options.

### Method
Not applicable (Command-line tool)

### Endpoint
Not applicable (Command-line tool)

### Parameters
#### Positional Arguments
- **<hwp5file>** (.hwp file to analyze)
- **<record-stream>** (Record-structured internal streams. e.g. DocInfo, BodyText/*)

#### Named Arguments
- **-h, --help** (boolean) - Show help message and exit
- **--file-format-version, -V** (string) - Specifies HWPv5 file format version of the standard input stream
- **--simple** (boolean) - Print records as simple tree. Default: False
- **--json** (boolean) - Print records as json. Default: False
- **--format** (string) - Print records formatted
- **--events** (boolean) - Print records as events. Default: False
- **--treegroup** (string) - Specifies the N-th subtree of the record structure.
- **--seqno** (string) - Print a model of <seqno>-th record

### Request Example
```bash
hwp5proc models samples/sample-5017.hwp DocInfo
hwp5proc models samples/sample-5017.hwp BodyText/Section0
hwp5proc models --simple samples/sample-5017.hwp bodytext/0
hwp5proc models --format='%(level)s %(tagname)s\n' samples/sample-5017.hwp bodytext/0
hwp5proc models --simple --treegroup=1 samples/sample-5017.hwp bodytext/0
hwp5proc models --simple --seqno=4 samples/sample-5017.hwp bodytext/0
hwp5proc models -V 5.0.1.7 < Section0.bin
```

### Response
Output varies based on the selected format (simple tree, JSON, events, formatted string).

#### Success Response (200)
- **Output** (string) - Formatted model data.

#### Response Example
(Output depends on the format specified, e.g., JSON string, plain text tree, event list)
```

--------------------------------

### hwp5proc header Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to print the file headers of HWP files. It requires the path to the HWP file as a positional argument.

```bash
usage: hwp5proc header [-h] <hwp5file>
```

--------------------------------

### cat Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Extracts specified internal streams from HWPv5 files to standard output.

```APIDOC
## cat

Extract out internal streams of .hwp files
Extract out the specified stream in the <hwp5file> to the standard output.

### Positional Arguments

- **hwp5file** (string) - Required - .hwp file to analyze
- **stream** (string) - Required - Internal path of a stream to extract

### Named Arguments

- **--vstreams** (boolean) - Optional - Process with virtual streams (i.e. parsed/converted form of real streams). Default: False
- **--ole** (boolean) - Optional - Treat <hwp5file> as an OLE Compound File. As a result, some streams will be presented as-is. (i.e. not decompressed). Default: False

### Request Example

```bash
hwp5proc cat samples/sample-5017.hwp BinData/BIN0002.jpg | file -
```

### Response Example

```json
{
  "example": "ccl: 0\ncert_drm: 0\ncert_encrypted: 0\ncert_signature_extra: 0\ncert_signed: 0\ncompressed: 1\ndistributable: 0\ndrm: 0\nhistory: 0\npassword: 0\nscript: 0\nsignature: HWP Document File\nversion: 5.0.1.7\nxmltemplate_storage: 0"
}
```
```

--------------------------------

### hwp5proc ls Subcommand Usage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to list streams within HWP files. It accepts optional named arguments `--vstreams` or `--ole` and requires the HWP file path.

```bash
usage: hwp5proc ls [-h] [--vstreams | --ole] <hwp5file>
```

--------------------------------

### hwp5odt Usage

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Command-line usage for the hwp5odt converter, which converts HWPv5 files to ODT format. Specify input file and optional arguments for output and features.

```bash
usage: hwp5odt [-h] [--version] [--loglevel LOGLEVEL] [--logfile LOGFILE]
               [--output OUTPUT] [--styles | --content | --document]
               [--embed-image | --no-embed-image]
               <hwp5file>

```

--------------------------------

### hwp5.binmodel Functions and Classes

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Functions and classes for processing HWP binary models.

```APIDOC
## hwp5.binmodel

### Classes

- **Hwp5File**: Represents an HWP file (also in hwp5.filestructure and hwp5.recordstream).
- **ModelJsonEncoder**: Encoder for converting models to JSON.

### Functions

- **init_record_parsing_context()**: Initializes the record parsing context.
- **model_to_json()**: Converts a model to JSON format.
- **parse_model()**: Parses the HWP model.
```

--------------------------------

### pyhwp Library Modules

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Overview of the core modules available in the pyhwp library.

```APIDOC
## Modules

- **hwp5.binmodel**: Module for binary model processing.
- **hwp5.dataio**: Module for data input/output operations.
- **hwp5.filestructure**: Module for HWP file structure handling.
- **hwp5.importhelper**: Module for import assistance.
- **hwp5.plat**: Platform-specific module.
- **hwp5.recordstream**: Module for record stream processing.
- **hwp5.storage**: Module for storage operations.
- **hwp5.tagids**: Module for HWP tag IDs.
- **hwp5.treeop**: Module for tree operations.
- **hwp5.utils**: Utility functions.
- **hwp5.xmlformat**: Module for XML format handling.
- **hwp5.xmlmodel**: Module for XML model processing.
```

--------------------------------

### Parse HWP Models with hwp5proc

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

The 'models' subcommand parses and prints binary models of HWP file record streams. It supports various output formats and filtering options like treegroup and seqno.

```bash
$ hwp5proc models samples/sample-5017.hwp DocInfo
$ hwp5proc models samples/sample-5017.hwp BodyText/Section0
```

```bash
$ hwp5proc models samples/sample-5017.hwp docinfo
$ hwp5proc models samples/sample-5017.hwp bodytext/0
```

```bash
$ hwp5proc models --simple samples/sample-5017.hwp bodytext/0
$ hwp5proc models --format='%(level)s %(tagname)s\n' \
        samples/sample-5017.hwp bodytext/0
```

```bash
$ hwp5proc models --simple --treegroup=1 samples/sample-5017.hwp bodytext/0
$ hwp5proc models --simple --seqno=4 samples/sample-5017.hwp bodytext/0
```

```bash
$ hwp5proc cat samples/sample-5017.hwp BodyText/Section0 > Section0.bin
$ hwp5proc models -V 5.0.1.7 < Section0.bin
```

--------------------------------

### records Subcommand

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Prints the record structure of .hwp file record streams.

```APIDOC
## records

Print the record structure of .hwp file record streams.
Print the record structure of the specified stream.

### Positional Arguments

- **hwp5file** (string) - Optional - .hwp file to analyze
- **record-stream** (string) - Optional - Record-structured internal streams. (e.g. DocInfo, BodyText/*)

### Named Arguments

- **--simple** (boolean) - Optional
- **--json** (boolean) - Optional
- **--raw** (boolean) - Optional
- **--raw-header** (boolean) - Optional
- **--raw-payload** (boolean) - Optional
- **--range** (string) - Optional - Specify a range of records.
- **--treegroup** (string) - Optional - Specify a tree group for records.
```

--------------------------------

### hwp5.filestructure Classes

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Information about classes related to HWP file structures.

```APIDOC
## hwp5.filestructure

### Classes

- **CompressedStorage**: Represents compressed storage within an HWP file.
- **Hwp5Compression**: Handles HWP compression.
  - **resolve_conversion_for()** (method): Resolves conversion for compression.
- **Hwp5File**: Represents an HWP file.
  - **resolve_conversion_for()** (method): Resolves conversion for the file.
- **Hwp5FileBase**: Base class for HWP file handling.
  - **resolve_conversion_for()** (method): Resolves conversion for the base file.

### Functions

- **is_hwp5file()**: Checks if a file is an HWP5 file.
```

--------------------------------

### Run diststream command

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Displays the usage information for the diststream subcommand, including optional arguments for decryption and raw output.

```bash
usage: hwp5proc diststream [-h] [--sha1 | --key] [--raw]
```

--------------------------------

### Process HWP Records with hwp5proc

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use the 'records' subcommand to print HWP file records in various formats like simple tree, JSON, or raw. It supports filtering by range and tree group.

```bash
$ hwp5proc records samples/sample-5017.hwp DocInfo
```

```bash
$ hwp5proc records samples/sample-5017.hwp DocInfo --range=0-2
```

```bash
$ hwp5proc records --raw samples/sample-5017.hwp DocInfo --range=0-2 > tmp.rec
$ hwp5proc records < tmp.rec
```

--------------------------------

### hwp5.dataio Classes and Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Details on classes and functions within the hwp5.dataio module, focusing on data types and processing.

```APIDOC
## hwp5.dataio

### Classes

- **basetype**: Base attribute for various data types.
  - **BSTR** (class): Represents a BSTR data type.
  - **BYTE** (class): Represents a BYTE data type.
  - **DOUBLE** (class): Represents a DOUBLE data type.
  - **HWPUNIT** (class): Represents a HWPUNIT data type.
  - **HWPUNIT16** (class): Represents a HWPUNIT16 data type.
  - **INT16** (class): Represents an INT16 data type.
  - **INT32** (class): Represents an INT32 data type.
  - **INT8** (class): Represents an INT8 data type.
  - **SHWPUNIT** (class): Represents a SHWPUNIT data type.
  - **UINT16** (class): Represents a UINT16 data type.
  - **UINT32** (class): Represents a UINT32 data type.
  - **UINT8** (class): Represents a UINT8 data type.
  - **WCHAR** (class): Represents a WCHAR data type.
  - **WORD** (class): Represents a WORD data type.

### Functions

- **decode_utf16le_with_hypua()**: Decodes UTF-16 LE with hypua encoding.
- **unicode_escape()**: Escapes Unicode characters.
- **unicode_unescape()**: Unescapes Unicode characters.
```

--------------------------------

### hwp5.utils Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Utility functions for various operations in the pyhwp library.

```APIDOC
## hwp5.utils

### Classes

- **GeneratorReader**: A generator-based reader.
- **GeneratorTextReader**: A generator-based text reader.

### Functions

- **generate_json_array()**: Generates a JSON array.
- **unicode_escape()**: Escapes Unicode characters.
- **unicode_unescape()**: Unescapes Unicode characters.
```

--------------------------------

### Initialize Record Parsing Context

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Initializes a context for parsing a given record. The context includes a shallow copy of the base context, the record itself, and the record's payload stream.

```python
def init_record_parsing_context(base, record):
    # Initialize a context to parse the given record
    # the initializations includes followings: - context = dict(base) - context[‘record’] = record - context[‘stream’] = record payload stream 
    context = dict(base)
    context['record'] = record
    context['stream'] = record.payload
    return context
```

--------------------------------

### rawunz Command

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Deflates a headerless zlib-compressed stream.

```APIDOC
## rawunz

### Description
Deflate an headerless zlib-compressed stream.

### Method
Not applicable (Command Line Tool)

### Endpoint
Not applicable (Command Line Tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
hwp5proc rawunz
```

### Response
#### Success Response (200)
Output depends on the input stream.

#### Response Example
None specified.
```

--------------------------------

### hwp5proc unpack Subcommand Usage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to extract all internal streams of an HWP file into a specified directory. It supports optional named arguments `--vstreams` or `--ole` and requires the HWP file path and an output directory.

```bash
usage: hwp5proc unpack [-h] [--vstreams | --ole] <hwp5file> [<out-directory>]
```

--------------------------------

### Unpack storage to a directory

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Unpacks the contents of a storage object into a specified directory on the filesystem. The output directory should not end with a '/'.

```python
hwp5.storage.unpack(stg, outbase)
```

--------------------------------

### hwp5proc records Subcommand Usage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to print the record structure of HWP file record streams. It accepts various named arguments for output format and filtering, and requires the HWP file path and optionally a record stream.

```bash
usage: hwp5proc records [-h]
                        [--simple | --json | --raw | --raw-header | --raw-payload]
                        [--range <range> | --treegroup <treegroup>]
                        [<hwp5file>] [<record-stream>]
```

--------------------------------

### hwp5txt: Text conversion

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Converts HWPv5 files to plain text format.

```APIDOC
## CLI hwp5txt

### Description
Converts an HWPv5 document into plain text format.

### Parameters
#### Positional Arguments
- **hwp5file** (string) - Required - The .hwp file to convert.

#### Named Arguments
- **--version** (flag) - Optional - Show program version.
- **--loglevel** (string) - Optional - Set log level.
- **--logfile** (string) - Optional - Set log file path.
- **--output** (string) - Optional - Output file path.
```

--------------------------------

### hwp5.treeop.build_subtree

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Builds a tree structure from an event-prefixed item stream.

```APIDOC
## build_subtree

### Description
Builds a tree from an (event, item) stream.

### Parameters
- **event_prefixed_items** (iterable) - Required - Stream of (event, item) tuples

### Response
- **tree** (tuple) - A tuple representing the root item and its children
```

--------------------------------

### hwp5proc cat Subcommand Usage

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Use this command to extract internal streams from HWP files to standard output. It supports optional named arguments `--vstreams` or `--ole`, requires the HWP file path, and the stream name.

```bash
usage: hwp5proc cat [-h] [--vstreams | --ole] <hwp5file> <stream>
```

--------------------------------

### hwp5proc xml

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Transforms HWP files into an XML format, with options for embedding binary data and controlling XML declaration.

```APIDOC
## hwp5proc xml

### Description
Transforms HWP files into an XML format, with options for embedding binary data and controlling XML declaration.

### Method
Not applicable (Command-line tool)

### Endpoint
Not applicable (Command-line tool)

### Parameters
#### Positional Arguments
- **<hwp5file>** (string) - .hwp file to analyze

#### Named Arguments
- **-h, --help** (boolean) - Show help message and exit
- **--embedbin** (boolean) - Embed BinData/* streams in the output XML. Default: False
- **--no-xml-decl** (boolean) - Do not output <?xml … ?> XML declaration. Default: False
- **--output** (string) - Output filename.
- **--format** (string) - "flat" or "nested" (default: "nested")
- **--no-validate-wellformed** (boolean) - Do not validate well-formedness of output. Default: False

### Request Example
```bash
hwp5proc xml samples/sample-5017.hwp > sample-5017.xml
hwp5proc xml --embedbin samples/sample-5017.hwp > sample-5017.xml
```

### Response
An XML representation of the HWP file content.

#### Success Response (200)
- **XML Output** (string) - The XML content of the HWP file.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<HWPDocument>
  <!-- ... XML content ... -->
</HWPDocument>
```
```

--------------------------------

### Build Subtree from Event-Prefixed Items

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Constructs a tree structure from a stream of (event, item) tuples. The function consumes events related to subtree construction and returns the root item with its children. It's crucial to manage the event stream correctly, especially the root item's events.

```python
hwp5.treeop.build_subtree(event_prefixed_items)
```

--------------------------------

### hwp5proc find

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Finds record models within HWP files based on specified predicates like model name or HWPTAG.

```APIDOC
## hwp5proc find

### Description
Finds record models within HWP files based on specified predicates like model name or HWPTAG.

### Method
Not applicable (Command-line tool)

### Endpoint
Not applicable (Command-line tool)

### Parameters
#### Positional Arguments
- **<hwp5files>** (string) - .hwp files to analyze (can be multiple)

#### Named Arguments
- **-h, --help** (boolean) - Show help message and exit
- **--from-stdin** (boolean) - Get filenames from stdin. Default: False
- **--model** (string) - Filter with record model name
- **--tag** (string) - Filter with record HWPTAG
- **--incomplete** (boolean) - Filter with incompletely parsed content. Default: False
- **--format** (string) - Record output format
- **--dump** (boolean) - Dump record. Default: False

### Request Example
```bash
hwp5proc find --model=Paragraph samples/*.hwp
hwp5proc find --tag=HWPTAG_PARA_TEXT samples/*.hwp
hwp5proc find --tag=66 samples/*.hwp
hwp5proc find --tag=HWPTAG_LIST_HEADER --incomplete --dump samples/*.hwp
```

### Response
Lists records that match the specified criteria.

#### Success Response (200)
- **Matching Records** (list of strings/objects) - Details of the found records.

#### Response Example
(Output depends on the format and dump options, typically a list of matching record identifiers or their content)
```

--------------------------------

### diststream Command

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Decodes a distribute document stream with various options.

```APIDOC
## diststream

### Description
Decode a distribute document stream.

### Method
Not applicable (Command Line Tool)

### Endpoint
Not applicable (Command Line Tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **--sha1** (flag) - Optional - Print SHA-1 value for decryption.
- **--key** (flag) - Optional - Print decrypted key.
- **--raw** (flag) - Optional - Print raw binary objects as is.

#### Request Body
None

### Request Example
```bash
hwp5proc diststream --sha1
hwp5proc diststream --key --raw
```

### Response
#### Success Response (200)
Output depends on the input stream and options selected.

#### Response Example
None specified.
```

--------------------------------

### hwp5html: HTML conversion

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Converts HWPv5 files to HTML format with options for CSS or HTML generation.

```APIDOC
## CLI hwp5html

### Description
Converts an HWPv5 document into HTML format.

### Parameters
#### Positional Arguments
- **hwp5file** (string) - Required - The .hwp file to convert.

#### Named Arguments
- **--version** (flag) - Optional - Show program version.
- **--loglevel** (string) - Optional - Set log level.
- **--logfile** (string) - Optional - Set log file path.
- **--output** (string) - Optional - Output file path.
- **--css** (flag) - Optional - Generate CSS.
- **--html** (flag) - Optional - Generate HTML.
```

--------------------------------

### Resolve conversion for storage item

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Returns a conversion function for a specified storage item. This method is available on Hwp5File, Hwp5FileBase, and also as a standalone function.

```python
resolve_conversion_for(name)
```

--------------------------------

### pyhwp Processor

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

The main pyhwp processor for HWPv5 files. It supports various subcommands for file analysis and manipulation.

```APIDOC
## `hwp5proc`: HWPv5 processor

Do various operations on HWPv5 files.

### Named Arguments

`--loglevel` (string) - Optional - Set log level.

`--logfile` (string) - Optional - Set log file.

### Subcommands

- version: Print the file format version of .hwp files.
- header: Print file headers of .hwp files.
- summaryinfo: Print summary informations of .hwp files.
- ls: List streams in .hwp files.
- cat: Extract out internal streams of .hwp files.
- unpack: Extract out internal streams of .hwp files into a directory.
- records: Print the record structure of .hwp file record streams.
- models: Print the record structure of .hwp file record streams.
- find: Find streams in .hwp files.
- xml: Extract XML data from .hwp files.
- rawunz: Uncompress raw streams.
- diststream: Process distributable streams.
```

--------------------------------

### hwp5.filestructure.is_hwp5file

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Checks if a given file is a valid HWP format v5 document.

```APIDOC
## FUNCTION hwp5.filestructure.is_hwp5file

### Description
Test whether the provided file is an HWP format v5 file.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the file to test.

### Response
- **bool** - Returns True if the file is a valid HWPv5 document, False otherwise.
```

--------------------------------

### Error Handling

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Exceptions and error types used within the pyhwp library.

```APIDOC
## Error Handling

- **Eof**: Exception raised when the end of data is reached unexpectedly.
- **OutOfData**: Exception raised when attempting to read beyond available data.
- **ParseError**: General exception for parsing errors.
```

--------------------------------

### Check if a file is HWP format v5

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Tests whether the given filename corresponds to an HWP format v5 file.

```python
hwp5.filestructure.is_hwp5file(filename)
```

--------------------------------

### hwp5proc records

Source: https://pyhwp.readthedocs.io/en/latest/hwp5proc.html

Processes and displays records from HWP files or standard input. Supports various output formats and range/group selections.

```APIDOC
## hwp5proc records

### Description
Processes and displays records from HWP files or standard input. Supports various output formats and range/group selections.

### Method
Not applicable (Command-line tool)

### Endpoint
Not applicable (Command-line tool)

### Parameters
#### Positional Arguments
- **<hwp5file>** (.hwp file to analyze)
- **<record-stream>** (Record-structured internal streams. e.g. DocInfo, BodyText/*)

#### Named Arguments
- **--simple** (boolean) - Print records as simple tree. Default: False
- **--json** (boolean) - Print records as json. Default: False
- **--raw** (boolean) - Print records as is. Default: False
- **--raw-header** (boolean) - Print record headers as is. Default: False
- **--raw-payload** (boolean) - Print record payloads as is. Default: False
- **--range** (string) - Specifies the range of the records. N-M means “from the record N to M-1 (excluding M)” N means just the record N
- **--treegroup** (string) - Specifies the N-th subtree of the record structure.
- **-V, --file-format-version** (string) - Specifies HWPv5 file format version of the standard input stream

### Request Example
```bash
hwp5proc records samples/sample-5017.hwp DocInfo
hwp5proc records samples/sample-5017.hwp DocInfo --range=0-2
hwp5proc records --raw samples/sample-5017.hwp DocInfo > tmp.rec
hwp5proc records < tmp.rec
```

### Response
Output varies based on the selected format (simple tree, JSON, raw, etc.).

#### Success Response (200)
- **Output** (string) - Formatted record data.

#### Response Example
(Output depends on the format specified, e.g., JSON string, plain text tree)
```

--------------------------------

### Make extended controls inline

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Inlines extended controls into paragraph texts. This function operates on event-prefixed MAC data.

```python
hwp5.xmlmodel.make_extended_controls_inline(event_prefixed_mac, stack=None)
```

--------------------------------

### hwp5.xmlmodel Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Functions for manipulating HWP data in XML format.

```APIDOC
## hwp5.xmlmodel

### Functions

- **make_extended_controls_inline()**: Makes extended controls inline.
- **make_paragraphs_children_of_listheader()**: Makes paragraphs children of the list header.
- **make_texts_linesegmented_and_charshaped()**: Processes text for line segmentation and character shaping.
- **restructure_tablebody()**: Restructures the table body.
- **tokenize_text_by_lang()**: Tokenizes text based on language.
- **wrap_section()**: Wraps a section of XML data.
```

--------------------------------

### hwp5.recordstream Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Functions for processing HWP record streams.

```APIDOC
## hwp5.recordstream

### Functions

- **group_records_by_toplevel()**: Groups records by their top-level identifier.
- **record_to_json()**: Converts a record to JSON format.
```

--------------------------------

### hwp5.utils.unicode_unescape

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Unescapes a provided unicode string.

```APIDOC
## unicode_unescape

### Description
Unescape a string.

### Parameters
- **s** (unicode) - Required - A string to unescape

### Response
- **result** (unicode) - The unescaped string
```

--------------------------------

### hwp5.treeop Functions

Source: https://pyhwp.readthedocs.io/en/latest/genindex.html

Functions for manipulating tree structures within HWP data.

```APIDOC
## hwp5.treeop

### Functions

- **build_subtree()**: Builds a subtree from HWP data.
- **prefix_ancestors()**: Retrieves ancestor nodes with a given prefix.
- **prefix_ancestors_from_level()**: Retrieves ancestor nodes from a specific level.
- **prefix_event()**: Handles prefix events in tree operations.
- **tree_events()**: Generates events from a tree structure.
- **tree_events_multi()**: Generates multiple events from a tree structure.
```

--------------------------------

### Convert a model to JSON

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Converts a given model into JSON format. Additional arguments and keyword arguments can be passed for customization.

```python
hwp5.binmodel.model_to_json(model, *args, **kwargs)
```

--------------------------------

### hwp5odt: ODT conversion

Source: https://pyhwp.readthedocs.io/en/latest/converters.html

Converts HWPv5 files to ODT format with options for specific XML generation and image embedding.

```APIDOC
## CLI hwp5odt

### Description
Converts an HWPv5 document into ODT format.

### Parameters
#### Positional Arguments
- **hwp5file** (string) - Required - The .hwp file to convert.

#### Named Arguments
- **--version** (flag) - Optional - Show program version.
- **--loglevel** (string) - Optional - Set log level.
- **--logfile** (string) - Optional - Set log file path.
- **--output** (string) - Optional - Output file path.
- **--styles** (flag) - Optional - Generate styles.xml.
- **--content** (flag) - Optional - Generate content.xml.
- **--document** (flag) - Optional - Generate .fodt.
- **--embed-image** (flag) - Optional - Embed images in output xml.
- **--no-embed-image** (flag) - Optional - Do not embed images in output xml.
```

--------------------------------

### Convert a record to JSON

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Converts a given record into JSON format. Additional arguments and keyword arguments can be passed for customization.

```python
hwp5.recordstream.record_to_json(record, *args, **kwargs)
```

--------------------------------

### Make texts linesegmented and charshaped

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Processes text chunks to be linesegmented and character-shaped. This function operates on event-prefixed MAC data.

```python
hwp5.xmlmodel.make_texts_linesegmented_and_charshaped(event_prefixed_mac)
```

--------------------------------

### hwp5.utils.unicode_escape

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Escapes a provided unicode string.

```APIDOC
## unicode_escape

### Description
Escape a string.

### Parameters
- **s** (unicode) - Required - A string to escape

### Response
- **result** (unicode) - The escaped string
```

--------------------------------

### Wrap section with SectionDef

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Wraps a section with `SectionDef`. An optional section ID can be provided. This function operates on event-prefixed MAC data.

```python
hwp5.xmlmodel.wrap_section(event_prefixed_mac, sect_id=None)
```

--------------------------------

### Group records by top-level trees

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Groups records by their top-level trees and returns an iterable of these groups. The `group_as_list` parameter controls whether groups are returned as lists.

```python
hwp5.recordstream.group_records_by_toplevel(records, group_as_list=True)
```

--------------------------------

### Make paragraphs children of listheader

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Configures paragraphs to be children of the listheader. This function allows specifying custom parent and child models.

```python
hwp5.xmlmodel.make_paragraphs_children_of_listheader(event_prefixed_mac, parentmodel=hwp5.binmodel.tagid56_list_header.ListHeader, childmodel=hwp5.binmodel.tagid50_para_header.Paragraph)
```

--------------------------------

### hwp5.dataio.decode_utf16le_with_hypua

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Decodes utf-16le encoded bytes containing Hanyang-PUA codes into a unicode string with Hangul Jamo codes.

```APIDOC
## decode_utf16le_with_hypua

### Description
Decodes utf-16le encoded bytes with Hanyang-PUA codes into a unicode string with Hangul Jamo codes.

### Parameters
- **bytes** (bytes) - Required - utf-16le encoded bytes with Hanyang-PUA codes

### Response
- **string** (unicode) - A unicode string with Hangul Jamo codes
```

--------------------------------

### Tokenize text by language

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Tokenizes text by language, grouping table columns in each row and wrapping them with `TableRow`. This function operates on event-prefixed MAC data.

```python
hwp5.xmlmodel.tokenize_text_by_lang(event_prefixed_mac)
```

--------------------------------

### Decode UTF-16LE with Hanyang-PUA to Hangul Jamo

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Decodes UTF-16LE encoded bytes containing Hanyang-PUA codes into a Unicode string with Hangul Jamo codes. Ensure input bytes are correctly encoded.

```python
hwp5.dataio.decode_utf16le_with_hypua(bytes)
```

--------------------------------

### Parse model based on HWPTAG

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Determines and parses a model based on its HWPTAG. This function is part of the binary model processing.

```python
hwp5.binmodel.parse_model(context, model)
```

--------------------------------

### hwp5.recordstream.record_to_json

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Converts a record object into a JSON representation.

```APIDOC
## FUNCTION hwp5.recordstream.record_to_json

### Description
Converts a record to a JSON format.

### Parameters
#### Request Body
- **record** (object) - Required - The record object to convert.

### Response
- **json** - The JSON representation of the record.
```

--------------------------------

### Restructure table body

Source: https://pyhwp.readthedocs.io/en/latest/hwp5.html

Restructures the table body by grouping table columns within each row and wrapping them with `TableRow`. This function operates on event-prefixed MAC data.

```python
hwp5.xmlmodel.restructure_tablebody(event_prefixed_mac)
```
Tokens:
Raw