### Install Documentation Packages

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command installs the packages required for generating project documentation using Sphinx. Assumes a virtual environment is active.

```bash
pip install '.[docs]'
```

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

### Install Development Dependencies

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command installs the necessary packages for development, including testing tools (py.test), a linter (ruff), a code formatter (black), and coverage tools. It assumes a virtual environment is active.

```bash
pip install '.[tests,dev]'
```

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

### Install Tox for Multi-Version Testing

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command installs Tox, a tool for automating Python testing across different versions. It's typically a one-time installation.

```bash
pip install tox
```

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

### Install Diceware in a Python Project

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

Demonstrates how to add 'diceware' as an install requirement in a Python project's `setup.py` file for use with setuptools. This ensures the 'diceware' package is available when the project is installed.

```python
from setuptools import setup
# ...
setup(
    name="myproject",
    # ...
    install_requires=[
        #  packages we depend on...
        'setuptools',
        'diceware',
        # ...
    ],
    # ...
)
```

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

### Generate HTML Documentation using Makefile

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command generates the project documentation in HTML format within the 'docs/_build/html/' directory using the provided Makefile in the 'docs/' directory. Assumes Sphinx and its dependencies are installed.

```bash
cd docs/
make
```

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

### Generate HTML Documentation with Sphinx

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command uses Sphinx to build the project documentation into HTML format, outputting it to the 'mydir/' directory. Assumes documentation packages are installed and a virtual environment is active.

```bash
sphinx-build docs/ mydir/
```

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

### Diceware Configuration File Example

Source: https://github.com/ulif/diceware/blob/master/README.rst

Custom default values for diceware can be set in a configuration file named `.diceware.ini` in the user's home directory or within the XDG config path. The example shows settings for the number of words, capitalization, special characters, delimiter, random source, and wordlist.

```ini
[diceware]
num = 7
caps = off
specials = 2
delimiter = "MYDELIMITER"
randomsource = "system"
wordlist = "en_securedrop"
```

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

### Python SystemRandomSource Class Example

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

This example showcases the `SystemRandomSource` class in Python, which utilizes the standard `SystemRandom` call, typically `/dev/urandom`, for randomness. It's the default source and is registered as an entry point. The `__init__` method is called with options, and the `choice` method selects an item from a given sequence.

```python
class SystemRandomSource(options):
    """A Random Source utilizing the standard Python SystemRandom call.

    As time of writing, SystemRandom makes use of `/dev/urandom` to get
    fairly useable random numbers.

    This source is registered as entry_point in setup.py under the name
    ‘system’ in the `diceware_random_sources` group.

    The constructor will be called with options at beginning of a
    programme run if the user has chosen the respective source of
    random.

    The SystemRandomSource is the default source.
    """
    def choice(self, sequence):
        """Pick one item out of sequence.

        The sequence will normally be a sequence of strings
        (wordlist), special chars, or numbers.

        Sequences can be (at least) lists, tuples and other types that
        have a len. Generators do not have to be supported (and are
        in fact not supported by this source).

        This method should return one item of the sequence picked based on
        the underlying source of randomness.

        In the long run, the choice should return each sequence item
        (i.e.: no items should be ‘unreachable’).

        It should also cope with any length > 0 of sequence and not
        break if a sequence is “too short” or “too long”. Empty
        sequences, however, might raise exceptions.
        """
        pass
```

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

### Diceware Configuration File Example

Source: https://context7.com/ulif/diceware/llms.txt

Demonstrates how to configure default Diceware settings persistently in a configuration file (e.g., '~/.diceware.ini'). This allows for consistent passphrase generation without specifying options each time.

```ini
[diceware]
num = 7
caps = off
specials = 2
delimiter = "-"
randomsource = "system"
wordlist = "en_eff"
```

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

### Using a Custom Diceware Wordlist from a File

Source: https://github.com/ulif/diceware/blob/master/README.rst

Users can provide their own wordlist by specifying a file path. Each line in the file is treated as a word. An empty file or a file with only whitespace lines will result in an empty output. The example demonstrates using `echo` to create a simple wordlist file.

```bash
echo -e "hi\nhello\n" > mywordlist.txt
diceware mywordlist.txt
HelloHelloHiHiHiHello
```

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

### Selecting a Specific Diceware Wordlist

Source: https://github.com/ulif/diceware/blob/master/README.rst

The `-w` option allows users to choose a specific wordlist for passphrase generation. The example shows how to use the 'en_orig' wordlist. Available wordlists can be listed using `diceware --help`.

```bash
diceware --wordlist en_orig
YorkNodePrickEchoToriNiobe
```

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

### Create Man Page from ReST Template

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command uses 'rst2man.py' to convert a ReStructuredText template file into a man page format, saving it as 'diceware.1'. It requires Sphinx and related tools to be installed.

```bash
rst2man.py docs/manpage.rst > diceware.1
```

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

### Run Project Tests

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command executes the project's test suite using pytest. It's used to verify the functionality and stability of the Diceware implementation. Assumes development dependencies are installed and a virtual environment is active.

```bash
pytest
```

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

### Python API Custom Random Sources Example

Source: https://context7.com/ulif/diceware/llms.txt

Shows how to integrate and use custom random sources within the Diceware Python API. This allows for advanced control over the randomness generation process.

```python
from diceware import get_passphrase, handle_options
from diceware.random_sources import SystemRandomSource

```

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

### Clone Diceware Repository

Source: https://github.com/ulif/diceware/blob/master/README.rst

This command clones the Diceware project repository from GitHub. It's the first step for developers to get the project code.

```bash
git clone https://github.com/ulif/diceware.git
```

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

### Support for PGP-Signed Wordlists in Python

Source: https://context7.com/ulif/diceware/llms.txt

Explains how to load and interact with PGP-signed wordlists. It demonstrates loading a signed wordlist, checking if it's signed, and iterating through its words. Note that signature verification itself is not implemented in this example snippet. Dependencies: `diceware.wordlist.WordList`.

```python
from diceware.wordlist import WordList

# Load signed wordlist (signature verification not implemented)
wordlist = WordList('/path/to/signed_wordlist.asc')

# Check if wordlist is signed
if wordlist.is_signed():
    print("Wordlist is PGP-signed")

# Iterate through words (signature headers/footers stripped)
words = list(wordlist)
print(f"Found {len(words)} words")
# Output: Found 7776 words
```

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

### Python RealDiceRandomSource Class Example

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

This example illustrates the `RealDiceRandomSource` class in Python, designed for randomness derived from physical dice rolls. It includes methods for picking an item from a sequence, calculating the number of required dice rolls, and performing pre-roll checks.

```python
class RealDiceRandomSource(options):
    """A source of randomness working with real dice."""
    def choice(self, sequence):
        """Pick one item out of sequence."""
        pass

    def get_num_rolls(self, seq_len):
        """Compute how many dice rolls we need to pick a value from a sequence"""
        pass

    def pre_check(self, num_rolls, sequence):
        """Checks performed before picking an item of a sequence.

        We make sure that num_rolls, the number of rolls, is in an
        acceptable range and issue an hint about the procedure.
        """
        pass
```

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

### Python Package Setup for Custom Randomness Source

Source: https://github.com/ulif/diceware/blob/master/docs/randomsources.md

Illustrates how to register a custom diceware random source within a Python package's setup.py file using entry_points. This allows diceware to discover and utilize the custom source.

```python
# setup.py

from setuptools import setup

setup(
    name='my_diceware_source_package',
    version='0.1',
    packages=['mypkg'],
    entry_points={
        'diceware_random_sources': [
          'mysrc = mypkg.sources:MySourceOfRandomness',
          # add more sources of randomness here...
        ],
    },
)

```

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

### Diceware: Using Real Dice for Randomness

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Explains and shows an example of using the `realdice` random source with the `-r` option, requiring user input from physical dice rolls to generate randomness.

```default
$ diceware -r realdice --dice-sides 6
Please roll 5 dice (or a single dice 5 times).
Enter your 5 dice results, separated by spaces: 6 4 2 3 1
Please roll 5 dice (or a single dice 5 times).
Enter your 5 dice results, separated by spaces: 5 4 3 6 2
...
UnleveledSimilarlyBackboardMurkyOasisReplay
```

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

### Create Custom Random Source Plugin in Python

Source: https://context7.com/ulif/diceware/llms.txt

Shows how to extend Diceware with custom randomness sources by creating a plugin. It defines a `CustomRandomSource` class that follows the plugin interface, including `__init__`, `choice`, and `update_argparser` methods. The example mentions how to register and use it. Dependencies: `diceware.random_sources.SystemRandomSource`.

```python
from diceware.random_sources import SystemRandomSource

class CustomRandomSource:
    """Example custom random source following diceware plugin interface."""

    def __init__(self, options):
        """Initialize with command-line options."""
        self.options = options

    def choice(self, sequence):
        """Pick one item from sequence using custom randomness."""
        # Implement your custom random selection logic
        import random
        return random.choice(sequence)

    @classmethod
    def update_argparser(cls, parser):
        """Add custom command-line arguments."""
        parser.add_argument(
            '--custom-option',
            help='Custom option for this random source'
        )
        return parser

# Register in __about__.py:
# random_sources = {
#     'custom': 'mypackage.mymodule:CustomRandomSource'
# }

# Use from command line:

```

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

### Discover Available Wordlists in Python

Source: https://context7.com/ulif/diceware/llms.txt

Provides functions to discover available wordlists and their locations. It demonstrates how to get a list of all wordlist names, the path to a specific wordlist, and the directories where wordlists are stored. Dependencies: `diceware.wordlist.get_wordlist_names`, `diceware.wordlist.get_wordlist_path`, `diceware.wordlist.get_wordlist_dirs`.

```python
from diceware.wordlist import (
    get_wordlist_names,
    get_wordlist_path,
    get_wordlist_dirs
)

# List all available wordlists
wordlists = get_wordlist_names()
print(wordlists)
# Output: ['ca', 'de', 'de_8k', 'en_adjectives', 'en_eff', 'en_nouns',
#          'es', 'fr', 'it', 'pt-br']

# Get path to specific wordlist
path = get_wordlist_path('en_eff')
print(path)
# Output: /usr/local/lib/python3.11/site-packages/diceware/wordlists/wordlist_en_eff.txt

# Show wordlist directories
dirs = get_wordlist_dirs()
print(dirs)
# Output: ['/usr/local/lib/python3.11/site-packages/diceware/wordlists',
#          '/home/user/.local/share/diceware',
#          '/usr/local/share/diceware',
#          '/usr/share/diceware']
```

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

### Piping a Custom Wordlist to Diceware

Source: https://github.com/ulif/diceware/blob/master/README.rst

A custom wordlist can be piped directly to diceware using a hyphen (-) as the filename argument. This avoids the need to create a temporary file. The example uses `echo` to pipe two words to diceware.

```bash
echo -e "hi\nhello\n" | diceware -
HiHiHelloHiHiHello
```

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

### Parse Configuration Files in Python

Source: https://context7.com/ulif/diceware/llms.txt

Illustrates reading and applying configuration settings from files using `diceware.config.get_config_dict`. It shows how to get default configurations from standard locations, list those locations, and parse specific custom configuration files. Dependencies: `diceware.config.get_config_dict`, `diceware.config.valid_locations`.

```python
from diceware.config import get_config_dict, valid_locations

# Get configuration from standard locations
config = get_config_dict()
print(config)
# Output: {'num': 6, 'caps': True, 'specials': 0, 'delimiter': '',
#          'randomsource': 'system', 'verbose': 0, 'wordlist': ['en_eff'],
#          'dice_sides': 6}

# Show configuration file locations
locations = valid_locations()
print(locations)
# Output: ['/home/user/.diceware.ini',
#          '/home/user/.config/diceware/diceware.ini',
#          '/etc/xdg/diceware/diceware.ini']

# Parse specific configuration files
custom_config = get_config_dict(['/path/to/custom.ini'])
print(custom_config['num'])
# Output: 7
```

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

### Generate Passphrases with Multiple Wordlists

Source: https://github.com/ulif/diceware/blob/master/docs/wordlists.md

This command generates passphrases by combining words from specified wordlists. The '-w' flag selects wordlists, '-n' specifies the number of words in the passphrase, and '-d' sets the delimiter between words. Each 'word' in the example is composed of one word from each provided list.

```bash
$ diceware -w en_adjectives en_nouns -n 2 -d '-'
lax-toast-strong-reason
```

```bash
$ diceware -w en_nouns en_adjectives -n 2 -d '-'
grains-honest-oxidant-happy
```

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

### Utility Functions for Wordlist Directory Management

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

These functions provide a way to retrieve the directories where wordlists are stored. They prioritize local installation directories, then XDG directories, and finally system-wide directories.

```python
def get_wordlist_dirs():
    # Returns a list of directories where wordlists can be found.
    # Prioritizes local install, XDG_DATA_HOME, then system paths.
    pass

def get_wordlist_names():
    # Returns a list of all available wordlist names.
    pass

def get_wordlist_path(name):
    # Returns the full path to a wordlist file given its name.
    # Raises ValueError for invalid names. Returns None if not found.
    pass

def get_wordlists_dir():
    # Returns the primary directory where wordlists are stored.
    pass
```

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

### Python Diceware Error Handling Example

Source: https://context7.com/ulif/diceware/llms.txt

Demonstrates how to handle common errors like invalid wordlist names or options when using the diceware Python API. It includes configurations for logging and catches specific exceptions such as ValueError, FileNotFoundError, and general Exceptions.

```python
from diceware import get_passphrase, handle_options
from diceware.wordlist import get_wordlist_path
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)

try:
    # Invalid wordlist name
    path = get_wordlist_path('nonexistent')
    if path is None:
        print("Wordlist not found")

    # Invalid options
    options = handle_options(['-n', '0'])  # Minimum is 1
    passphrase = get_passphrase(options)

except ValueError as e:
    print(f"Invalid value: {e}")
except FileNotFoundError as e:
    print(f"File not found: {e}")
except Exception as e:
    print(f"Error: {e}")
```

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

### Using Custom Randomness Sources with Diceware

Source: https://github.com/ulif/diceware/blob/master/README.rst

Diceware allows specifying alternative sources of randomness using the `-r` or `--randomsource` option. The example demonstrates using a 'realdice' source, which prompts the user to input dice rolls. The `--dice-sides` option can specify the number of sides on the dice.

```bash
diceware -r realdice --dice-sides 6
Please roll 5 dice (or a single dice 5 times).
Enter your 5 dice results, separated by spaces: 6 4 2 3 1
Please roll 5 dice (or a single dice 5 times).
Enter your 5 dice results, separated by spaces: 5 4 3 6 2
...
UnleveledSimilarlyBackboardMurkyOasisReplay
```

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

### Generate Default Passphrase (Command Line)

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Executes the diceware command-line tool to generate a default passphrase. The default passphrase consists of six words, with the first character of each word capitalized, and no separator characters. This is a simple way to get a secure passphrase quickly.

```shell
$ diceware
MyraPend93rdSixthEagleAid
```

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

### Install Diceware Python Package (pip)

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Installs the diceware Python package using pip. This command assumes pip is installed and configured on your system. The installation method may vary slightly depending on your operating system.

```shell
$ pip install diceware
```

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

### Create and Activate Virtual Environment

Source: https://github.com/ulif/diceware/blob/master/README.rst

This sequence of commands creates a Python virtual environment named 'py311' using Python 3.11 and then activates it. This isolates project dependencies.

```bash
cd diceware/
virtualenv -p /usr/bin/python3.11 py311
source py311/bin/activate
```

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

### Using Custom Wordlists with Diceware via File

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Illustrates how to use a custom wordlist by providing a file path. Each line in the file is treated as a word. Empty lines and lines with only whitespace are ignored.

```bash
$ echo -e "hi\nhello\n" > mywordlist.txt
$ diceware mywordlist.txt
HelloHelloHiHiHiHello
```

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

### Get Available Random Sources

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.get_random_sources` function retrieves a dictionary of all registered Diceware random sources. These sources are implemented as entry points under the 'diceware_random_source' group and must provide a `choice` method.

```python
diceware.get_random_sources()
```

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

### Show Diceware Wordlist Directories

Source: https://github.com/ulif/diceware/blob/master/docs/wordlists.md

This command lists all directories where Diceware searches for wordlist files. The first directory listed is typically where the built-in wordlists are stored. Users can place custom wordlists in these directories following a specific naming convention.

```bash
$ diceware --show-wordlist-dirs
/path/to/some/directory
/path/to/other/directory
...
```

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

### Main Program Entry Point

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.main` function serves as the primary entry point when the 'diceware' script is executed. It handles argument processing and orchestrates the Diceware passphrase generation process.

```python
diceware.main(args=None)
```

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

### Get Configuration Dictionary

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.config.get_config_dict` function retrieves Diceware configuration values from specified files. It returns a dictionary of options, ensuring values match types defined in `defaults_dict` and stripping quotes from string values.

```python
diceware.config.get_config_dict(path_list=None, defaults_dict={'caps': True, 'delimiter': '', 'dice_sides': 6, 'num': 6, 'randomsource': 'system', 'specials': 0, 'verbose': 0, 'wordlist': ['en_eff']}, section='diceware')
```

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

### Use a Custom Wordlist Stored in a Diceware Directory

Source: https://github.com/ulif/diceware/blob/master/docs/wordlists.md

This command generates a passphrase using a custom wordlist that has been placed in one of the directories searched by Diceware. The wordlist file must be named 'wordlist_NAME.txt' or 'wordlist_NAME.asc' (or similar extensions), and '-w NAME' is used to reference it. This allows for persistent storage and easy access to custom wordlists.

```bash
$ diceware -w MY_SPECIAL_NAME
```

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

### Append Special Characters to Words in Python

Source: https://context7.com/ulif/diceware/llms.txt

Demonstrates appending random special characters to a given word. It uses the `diceware.append_special_char` function and predefined `SPECIAL_CHARS`. The example shows adding one and then multiple special characters. Dependencies: `diceware.append_special_char`, `diceware.SPECIAL_CHARS`, `random.SystemRandom`.

```python
from diceware import append_special_char, SPECIAL_CHARS
from random import SystemRandom

word = "Passphrase"
rnd = SystemRandom()

# Add one special character
enhanced = append_special_char(word, SPECIAL_CHARS, rnd)
print(enhanced)
# Output: Passphrase#

# Add multiple special characters
for _ in range(3):
    word = append_special_char(word, SPECIAL_CHARS, rnd)
print(word)
# Output: Passphrase#5!
```

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

### Command-Line Usage with Custom Random Source

Source: https://github.com/ulif/diceware/blob/master/docs/randomsources.md

Demonstrates how to invoke diceware using a custom random source named 'mysrc'. This assumes the custom source has been correctly registered as a Python entry point.

```bash
$ diceware -r mysrc

```

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

### Using Custom Wordlists with Diceware via Pipe

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Demonstrates using a custom wordlist by piping it directly to the diceware command using a dash (-) as the filename. Empty lines are ignored.

```bash
$ echo -e "hi\nhello\n" | diceware -
HiHiHelloHiHiHello
```

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

### Load and Use Custom Wordlist in Python

Source: https://context7.com/ulif/diceware/llms.txt

Demonstrates loading and iterating through a custom wordlist from a file. It first creates a temporary file with words, then loads it using `diceware.wordlist.WordList`. Finally, it generates a custom passphrase using `random.SystemRandom` and the loaded words. Dependencies: `diceware.wordlist.WordList`, `random.SystemRandom`.

```python
from diceware.wordlist import WordList
from random import SystemRandom

# Create temporary wordlist
with open('/tmp/mywords.txt', 'w') as f:
    f.write('alpha\nbravo\ncharlie\ndelta\necho\nfoxtrot\n')

# Load and use wordlist
wordlist = WordList('/tmp/mywords.txt')
words = list(wordlist)
print(words)
# Output: ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot']

# Generate custom passphrase
rnd = SystemRandom()
passphrase = ''.join([rnd.choice(words).capitalize() for _ in range(4)])
print(passphrase)
# Output: BravoEchoDeltaFoxtrot
```

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

### Using Specific Wordlists in Diceware

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Demonstrates how to specify a particular wordlist for passphrase generation using the -w option. Lists available wordlists can be found with 'diceware --help'.

```bash
$ diceware --wordlist en_orig
YorkNodePrickEchoToriNiobe
```

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

### Diceware Command-line Help and Usage

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Displays the help message for the diceware command-line tool, listing all available options and their descriptions. This is useful for understanding the full range of customization available for passphrase generation.

```default
$ diceware --help
usage: diceware [-h] [-n NUM] [-c | --no-caps] [-s NUM] [-d DELIMITER] [-r SOURCE] [-w [NAME [NAME ...]]] [--dice-sides N] [-v] [--version] [INFILE]

Create a passphrase

positional arguments:
  INFILE                Input wordlist. `-' will read from stdin.

optional arguments:
  -h, --help            show this help message and exit
  -n NUM, --num NUM     number of words to concatenate. Default: 6
  -c, --caps            Capitalize words. This is the default.
  --no-caps             Turn off capitalization.
  -s NUM, --specials NUM
                        Append NUM special chars at the end of the generated
                        passphrase.
  -d DELIMITER, --delimiter DELIMITER
                        Separate words by DELIMITER. Empty string by default.
  -r SOURCE, --randomsource SOURCE
                        Get randomness from this source. Possible values:
                        `realdice', `system'. Default: system
  -w [NAME [NAME ...]], --wordlist [NAME [NAME ...]]
                        Use words from this wordlist. Possible values: `ca`,
                        `de', `de_8k', `en_adjectives', `en_eff', `en_nouns',
                        `en_securedrop', `es`, `fr`, `it`, `pt-br'.
                        Wordlists are stored in the folders displayed below.
                        Default: en_eff
  -v, --verbose         Be verbose. Use several times for increased verbosity.
  --version             output version information and exit.
  --show-wordlist-dirs  Output directories we look up to find wordlists and exit.

Arguments related to `realdice' randomsource:
  --dice-sides N        Number of sides of dice. Default: 6

Use --show-wordlist-dirs to list directories where you can store custom wordlists.

```

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

### Read Wordlist from Standard Input in Python

Source: https://context7.com/ulif/diceware/llms.txt

Shows how to process wordlists from standard input, useful for pipes or redirected input. It simulates `sys.stdin` using `io.StringIO` and then loads the wordlist using `diceware.wordlist.WordList('-')`. Dependencies: `diceware.wordlist.WordList`, `sys`, `io.StringIO`.

```python
from diceware.wordlist import WordList
import sys
from io import StringIO

# Simulate stdin input
sys.stdin = StringIO('alpha\nbravo\ncharlie\ndelta\n')

# Read from stdin (use '-' as path)
wordlist = WordList('-')
words = list(wordlist)
print(words)
# Output: ['alpha', 'bravo', 'charlie', 'delta']
```

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

### Handle Commandline Options

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.handle_options` function is responsible for processing command-line arguments provided to the Diceware script. It parses these arguments to configure the passphrase generation process.

```python
diceware.handle_options(args)
```

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

### Generate Passphrase with a Custom Wordlist File

Source: https://github.com/ulif/diceware/blob/master/docs/wordlists.md

This command generates a passphrase using a custom wordlist file. The filename is provided directly to the 'diceware' command. The output passphrase is constructed from words within the specified text file.

```bash
$ diceware mywordlist.txt
HiHelloHelloHiHiHi
```

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

### Parse Configuration Files

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.config.get_configparser` function parses configuration files from a given list of paths. It returns a list of successfully read file paths and a configuration parser object.

```python
diceware.config.get_configparser(path_list=None)
```

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

### Split String into Wordlist Names

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

The `diceware.config.string_to_wlist_list` function takes a string and splits it into a list of valid wordlist names. This is useful for parsing configuration settings that specify multiple wordlists.

```python
diceware.config.string_to_wlist_list(text)
```

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

### Command-Line Usage with Real Dice

Source: https://github.com/ulif/diceware/blob/master/docs/randomsources.md

Shows how to use the 'realdice' option with the diceware command-line tool. It prompts the user to roll physical dice and enter the results to generate a passphrase.

```bash
$ diceware -r realdice
Warning: entropy is reduced!
Please roll 5 dice (or a single dice 5 times).
What number shows dice number 1? 1
What number shows dice number 2? 2
What number shows dice number 3? 3
What number shows dice number 4? 4
What number shows dice number 5? 5
Warning: entropy is reduced!
Please roll 5 dice (or a single dice 5 times).
What number shows dice number 1? 2
What number shows dice number 2? 3
What number shows dice number 3? 3
What number shows dice number 4? 5
What number shows dice number 5? 1

...

What number shows dice number 5? 3
AnyDogmaShrikeSageSableHoar

```

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

### Python System Randomness Class

Source: https://github.com/ulif/diceware/blob/master/docs/randomsources.md

Demonstrates the structure of a custom source of randomness for diceware using Python. It requires a class with an __init__ method accepting options and a choice(sequence) method to select an element from a given sequence.

```python
class MySourceOfRandomness(object):
    """Tell about your source..."""
    def __init__(self, options):
        # initialize, etc.
        pass

    def choice(self, sequence):
        # return one of the elements in `sequence`
        pass

```

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

### Registering Custom Random Sources in __about__.py

Source: https://github.com/ulif/diceware/blob/master/docs/api.md

This code snippet demonstrates how to register a custom random source within the `__about__.py` file. It shows the expected dictionary structure for mapping a source name to its corresponding class path. This allows diceware to discover and utilize the custom source.

```default
# ...
random_sources' = {
     # ...
    'myrandom': 'mypkg.mymodule:MyRandomSource',
    'myothersrc': 'mypkg.mymodule:MyOtherSource',
}
# ...
```

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

### CLI Passphrase Generation with Alternative Wordlists

Source: https://context7.com/ulif/diceware/llms.txt

Utilizes different language-specific wordlists (e.g., German 'de', French 'fr') or combines multiple lists (e.g., 'en_adjectives', 'en_nouns') using the '-w' option.

```bash
$ diceware -w de
SchlossGartenFensterBuchTischStuhl

$ diceware -w fr
MaisonChienChatPorteFenetreJardin

$ diceware -n 3 -w en_adjectives en_nouns
TediousPerimeterMassiveOceanBrilliantSunset
```

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

### Generating Adjective-Noun Phrases with Diceware

Source: https://github.com/ulif/diceware/blob/master/docs/readme.md

Shows how to create passphrase phrases by combining adjectives and nouns using the -n and -w options with specified wordlists. This feature is currently English-only.

```bash
$ diceware -n 1 -w en_adjectives en_nouns
TediousPerimeter
```

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

### Python API Passphrase Generation with Customized Options

Source: https://context7.com/ulif/diceware/llms.txt

Allows customizing passphrase generation by parsing command-line style arguments or by programmatically setting option attributes. This provides fine-grained control over passphrase properties.

```python
from diceware import get_passphrase, handle_options

# Parse command-line style arguments
options = handle_options(['-n', '4', '-d', '-', '--no-caps', '-s', '2'])
passphrase = get_passphrase(options)
print(passphrase)
# Output: ocean-blend-baron-ferry#5

# Create options programmatically
options = handle_options([])
options.num = 5
options.delimiter = '_'
options.caps = True
options.specials = 1
passphrase = get_passphrase(options)
print(passphrase)
# Output: Violet_Paradox_Imaginary_Whenever_Harddisk!
```