### Install readmdict package

Source: https://github.com/ffreemt/readmdict/blob/master/README.md

Install the readmdict package via pip or poetry.

```bash
pip install readmdict
# or poetry add readmdict
```

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

### Install python-lzo dependency

Source: https://github.com/ffreemt/readmdict/blob/master/README.md

Install the required LZO compression library for full functionality.

```bash
pip install python-lzo
# or poetry add python-lzo
```

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

### Install readmdict and dependencies

Source: https://context7.com/ffreemt/readmdict/llms.txt

Use pip or poetry to install the library. LZO compression support requires the python-lzo package.

```bash
pip install readmdict
# or
poetry add readmdict
```

```bash
pip install python-lzo
```

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

### Display CLI help summary

Source: https://github.com/ffreemt/readmdict/blob/master/README.md

Print a short summary of command-line options.

```bash
readmdict -h
```

```bash
python -m readmdict -h
```

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

### CLI: Show Help and Options

Source: https://context7.com/ffreemt/readmdict/llms.txt

Display the help message and all available command-line options for the readmdict tool using the '-h' or '--help' flag.

```bash
# Show help and all available options
readmdict -h
# Output:
# usage: readmdict [-h] [-x] [-s] [-d DATAFOLDER] [-e ENCODING] [-p PASSCODE] [filename]
#
# positional arguments:
#   filename              mdx file name
#
# optional arguments:
#   -h, --help            show this help message and exit
#   -x, --extract         extract mdx to source format and extract files from mdd
#   -s, --substyle        substitute style definition if present
#   -d DATAFOLDER, --datafolder DATAFOLDER
#                         folder to extract data files from mdd
#   -e ENCODING, --encoding ENCODING
#                         character encoding
#   -p PASSCODE, --passcode PASSCODE
#                         register_code,email_or_deviceid
```

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

### Browse file meta information via CLI

Source: https://github.com/ffreemt/readmdict/blob/master/README.md

Launch the interactive browser or print meta information for a specific file.

```bash
readmdict
```

```bash
python -m readmdict
```

```bash
readmdict file.mdx
```

```bash
python -m readmdict file.mdx
```

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

### Prepare Passcode and Read Encrypted Dictionary/Resource

Source: https://context7.com/ffreemt/readmdict/llms.txt

Prepare the passcode as a tuple of (regcode_bytes, userid_string) for encrypted dictionaries and resources. Ensure the regcode is a 32-character hex string.

```python
import codecs
from readmdict import MDX, MDD

regcode_hex = "0123456789abcdef0123456789abcdef"  # 32-char hex string
regcode = codecs.decode(regcode_hex, 'hex')
userid = "user@example.com"  # or device ID
passcode = (regcode, userid)

# Read encrypted dictionary
mdx = MDX('encrypted_dict.mdx', passcode=passcode)
print(f"Entries: {len(mdx)}")

# Read encrypted resource file
mdd = MDD('encrypted_dict.mdd', passcode=passcode)
print(f"Resources: {len(mdd)}")
```

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

### Read MDX with style substitution

Source: https://context7.com/ffreemt/readmdict/llms.txt

Enable substyle to automatically expand inline style references within dictionary definitions.

```python
from readmdict import MDX

# Enable style substitution for formatted output
mdx = MDX('styled_dict.mdx', substyle=True)

# Get entries with expanded styles
for key, value in mdx.items():
    definition = value.decode('utf-8')
    # Style markers like `1` are replaced with actual CSS classes
    print(definition[:200])
    break
```

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

### Extract MDX files via command line

Source: https://github.com/ffreemt/readmdict/blob/master/README-org.md

Use the command line interface to extract dictionary definitions and associated data files.

```bash
$ python readmdict.py -x oald8.mdx
```

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

### Read encrypted dictionaries

Source: https://context7.com/ffreemt/readmdict/llms.txt

Import necessary modules to begin handling password-protected files.

```python
from readmdict import MDX, MDD
import codecs
```

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

### Access MDX and MDD files in Python

Source: https://github.com/ffreemt/readmdict/blob/master/README.md

Use the MDX and MDD classes to extract headwords and content from dictionary files.

```python
from readmdict import MDX, MDD

filename = "some.mdx"
headwords = [*MDX(filename).header]
print(headwords[:10])  # fisrt 10 in bytes format
for hdw in headwords[:10]:
	print(hdw.decode())   # fisrt 10 in string format

items = [*MDX(filename).items()]
for key, val in items[:10]:
	print(key.decode(), val.decode())  # first 10 entries

# read an mdd file
filename = "some.mdd"
items = MDD(filename).items()
idx = 0
for filename, content in items:
  idx += 1
  if idx > 10:
    break
	print(filename.decode(), content.decode())  # first 10 entries
```

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

### CLI: Display Meta Information for MDX File

Source: https://context7.com/ffreemt/readmdict/llms.txt

Use the readmdict CLI to display meta information of an MDX file. This includes the number of entries, engine versions, encoding, format, and title.

```bash
# Display meta information for an MDX file
readmdict dictionary.mdx
# Output:
# ======== dictionary.mdx ========
#   Number of Entries : 42481
#   GeneratedByEngineVersion : 2.0
#   RequiredEngineVersion : 2.0
#   Encoding : UTF-8
#   Format : Html
#   Title : Oxford Dictionary
```

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

### Read MDX and MDD files as a Python module

Source: https://github.com/ffreemt/readmdict/blob/master/README-org.md

Import the MDX and MDD classes to programmatically access dictionary entries and resource data.

```python
In [1]: from readmdict import MDX, MDD
```

```python
In [2]: mdx = MDX('oald8.mdx')

In [3]: items = mdx.items()

In [4]: items.next()
```

```python
In [5]: mdd = MDD('oald8.mdd')

In [6]: items = mdd.items()

In [7]: items = mdd.next()
```

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

### CLI: Read Encrypted Dictionary with Passcode

Source: https://context7.com/ffreemt/readmdict/llms.txt

Provide the passcode directly on the command line for encrypted dictionaries using the '-p' or '--passcode' option. The format is 'regcode_hex,userid'.

```bash
# Read encrypted dictionary with passcode
readmdict -p "0123456789abcdef0123456789abcdef,user@example.com" encrypted.mdx
```

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

### Read MDX dictionary files

Source: https://context7.com/ffreemt/readmdict/llms.txt

The MDX class parses dictionary files to access metadata, headwords, and definitions.

```python
from readmdict import MDX

# Initialize MDX reader with a dictionary file
mdx = MDX('oxford.mdx')

# Get the number of dictionary entries
print(f"Total entries: {len(mdx)}")  # Output: Total entries: 42481

# Access dictionary header metadata
for key, value in mdx.header.items():
    print(f"{key.decode()}: {value.decode()}")
# Output:
# GeneratedByEngineVersion: 2.0
# RequiredEngineVersion: 2.0
# Encoding: UTF-8
# Format: Html
# Title: Oxford Advanced Learner's Dictionary

# Iterate over all dictionary keys
headwords = [*mdx.keys()]
print(headwords[:5])  # First 5 headwords in bytes format
# Output: [b'a', b'A', b'AA', b'AAA', b'aardvark']

# Get all dictionary entries as (key, value) tuples
items = [*mdx.items()]
for key, value in items[:3]:
    print(f"Word: {key.decode()}")
    print(f"Definition: {value.decode()[:100]}...")
    print("---")
# Output:
# Word: a
# Definition: <div class="entry"><span class="hw">a</span> <span class="pos">indefinite article</span>...
# ---
```

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

### Read MDD resource files

Source: https://context7.com/ffreemt/readmdict/llms.txt

The MDD class extracts binary resources like images, audio, and CSS files associated with MDict dictionaries.

```python
from readmdict import MDD

# Initialize MDD reader with a resource file
mdd = MDD('oxford.mdd')

# Get the number of resource files
print(f"Total resources: {len(mdd)}")  # Output: Total resources: 208

# Access resource file header metadata
for key, value in mdd.header.items():
    print(f"{key.decode()}: {value.decode()}")

# Iterate over all resource files
for filename, content in mdd.items():
    filepath = filename.decode('utf-8')
    print(f"File: {filepath}, Size: {len(content)} bytes")

    # Save specific file types
    if filepath.endswith('.css'):
        with open('extracted_style.css', 'wb') as f:
            f.write(content)
    elif filepath.endswith('.mp3'):
        # Save pronunciation audio
        output_path = filepath.replace('\\', '/').lstrip('/')
        with open(output_path, 'wb') as f:
            f.write(content)
    break  # Process first entry only for demo
# Output:
# File: \css\dictionary.css, Size: 4523 bytes
```

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

### Python: Full Extraction Workflow for Dictionary and Resources

Source: https://context7.com/ffreemt/readmdict/llms.txt

A comprehensive Python function to extract dictionary entries to a text file and associated resources from an MDD file into a specified output directory. Handles creation of directories and file writing.

```python
from readmdict import MDX, MDD
import os

def extract_dictionary(mdx_path, output_dir='output'):
    """Extract MDX dictionary and MDD resources to output directory."""
    os.makedirs(output_dir, exist_ok=True)

    # Extract dictionary entries
    mdx = MDX(mdx_path)
    base_name = os.path.splitext(os.path.basename(mdx_path))[0]

    # Write entries to text file
    txt_path = os.path.join(output_dir, f'{base_name}.txt')
    with open(txt_path, 'wb') as f:
        for key, value in mdx.items():
            f.write(key + b'\r\n')
            f.write(value)
            if not value.endswith(b'\n'):
                f.write(b'\r\n')
            f.write(b'</>\r\n')
    print(f"Extracted {len(mdx)} entries to {txt_path}")

    # Extract companion MDD resources if exists
    mdd_path = mdx_path.replace('.mdx', '.mdd')
    if os.path.exists(mdd_path):
        mdd = MDD(mdd_path)
        data_dir = os.path.join(output_dir, 'data')

        for filename, content in mdd.items():
            # Convert Windows path to local path
            rel_path = filename.decode('utf-8').replace('\\', os.sep).lstrip(os.sep)
            full_path = os.path.join(data_dir, rel_path)

            # Create parent directories
            os.makedirs(os.path.dirname(full_path), exist_ok=True)

            # Write resource file
            with open(full_path, 'wb') as f:
                f.write(content)

        print(f"Extracted {len(mdd)} resources to {data_dir}")

# Usage
extract_dictionary('oxford.mdx', 'extracted_oxford')
# Output:
# Extracted 42481 entries to extracted_oxford/oxford.txt
# Extracted 208 resources to extracted_oxford/data
```

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

### CLI: Extract with Custom Data Folder

Source: https://context7.com/ffreemt/readmdict/llms.txt

Specify a custom directory name for extracting MDD resources using the '-d' or '--datafolder' option. This allows for better organization of extracted files.

```bash
# Extract with custom data folder
readmdict -x -d resources dictionary.mdx
# Creates: resources/ folder instead of data/
```

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

### CLI: Enable Style Substitution During Extraction

Source: https://context7.com/ffreemt/readmdict/llms.txt

Use the '-s' or '--substyle' option to enable style substitution during extraction. This can be useful for processing dictionaries that rely on specific styling definitions.

```bash
# Enable style substitution during extraction
readmdict -x -s dictionary.mdx
```

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

### CLI: Extract MDX to Text and MDD Resources

Source: https://context7.com/ffreemt/readmdict/llms.txt

Extracts MDX dictionary entries to text format and companion MDD resources to a 'data' folder. This is useful for converting dictionary content or accessing associated media files.

```bash
# Extract MDX to text format and MDD resources to data folder
readmdict -x dictionary.mdx
# Creates: dictionary.txt (all entries)
# Creates: data/ folder (all resources from companion .mdd file)
```

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

### Read MDX with custom encoding

Source: https://context7.com/ffreemt/readmdict/llms.txt

Specify an encoding parameter to handle non-standard character sets like GB18030.

```python
from readmdict import MDX

# Read a Chinese dictionary with specific encoding
mdx = MDX('chinese_dict.mdx', encoding='GB18030')

# Access entries
for key, value in mdx.items():
    word = key.decode('utf-8')
    definition = value.decode('utf-8')
    print(f"{word}: {definition[:50]}...")
    break
# Output: 你好: <div>nǐ hǎo - hello, hi</div>...
```

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

### CLI: Specify Encoding Explicitly

Source: https://context7.com/ffreemt/readmdict/llms.txt

Explicitly set the character encoding for extraction using the '-e' or '--encoding' option. This is important for dictionaries with non-standard encodings.

```bash
# Specify encoding explicitly
readmdict -x -e UTF-8 dictionary.mdx
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.