lain-upload

https://github.com/necraul/lain-upload
Admin
lain-upload is a Python command-line tool that uploads files to hosting services such as catbox,...
Tokens:54,984
Snippets:466
Trust Score:6.7
License:LGPL-2.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### JSON configuration file example

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Shows the structure of the JSON config file with default_host and per-host options (auth, expire_after, long_filenames, single_view). Default host is "catbox".

```json
{
  "default_host": "catbox",
  "hosts": {
    "catbox": {
      "auth": null
    },
    "litterbox": {
      "expire_after": "72h",
      "long_filenames": false
    },
    "waifuvault": {
      "expire_after": "12h",
      "long_filenames": false,
      "single_view": false,
    },
    "sharey": {
      "auth": null,
      "expire_after": "24h",
      "single_view": false,
    },
    "gofile": {
      "auth": null
    }
  }
}
```

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

### Install and run lain-upload with uv

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Shows the recommended uv-based methods: permanent installation with uv tool install, one-off execution with uvx, and script/ad-hoc usage with uv run. All use the desktop version with clipboard support.

```sh
# Permanent isolated installation
uv tool install "lain-upload[clipboard]"
```

```sh
# Run once without installing
uvx --with "lain-upload[clipboard]" lain-upload <file1> <file2> <file3>
```

```sh
# Run in scripts or ad-hoc environments
uv run --with "lain-upload[clipboard]" lain-upload <file1> <file2> <file3>
```

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

### Set up lain-upload from source for development

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Clones the repository, installs all development dependencies with uv sync --dev, sets up the pre-commit hook, and shows how to run linters, the local version, and tests.

```sh
# Clone the repository and navigate to it
git clone git@github.com:NecRaul/lain-upload.git
cd lain-upload
```

```sh
# Install environment and all development dependencies (mandatory and optional)
uv sync --dev
```

```sh
# Install pre-commit hook
uv run pre-commit install
```

```sh
# Optional: Run all linters and type checkers manually
uv run pre-commit run --all-files
```

```sh
# Run the local version
uv run lain-upload <file1> <file2> <file3>
```

```sh
# Run tests
uv run pytest tests
```

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

### Install lain-upload with pip (basic)

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Installs the desktop version of lain-upload with clipboard support using pip. Use this for a standard Python environment.

```sh
pip install "lain-upload[clipboard]"
```

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

### Basic usage example

Source: https://github.com/necraul/lain-upload

Uploads a file and prints the resulting public URL.

```python
from pathlib import Path

from lain_upload.uploader import BuzzheavierUploader

url = BuzzheavierUploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://buzzheavier.com/xxxx
```

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

### Usage example: load effective config, get host options, save default config

Source: https://github.com/necraul/lain-upload

Shows reading an effective config (existing file merged over defaults), obtaining per-host kwargs for the uploader constructor (e.g., {'expire_after': '12h', 'long_filenames': False}), and writing a default configuration. The save_config call returns the absolute path.

```python
from lain_upload.config import (
    DEFAULT_CONFIG,
    get_host_options,
    load_effective_config,
    save_config,
)

# read effective config (existing file merged over defaults)
cfg = load_effective_config(path="config.json")

# per-host kwargs for the uploader constructor
kwargs = get_host_options(cfg, "litterbox")
# {'expire_after': '12h', 'long_filenames': False}

# write a default configuration
path = save_config(DEFAULT_CONFIG, "config.json")
print(path)  # /abs/path/config.json
```

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

### ShareyUploader with all options and error handling

Source: https://github.com/necraul/lain-upload

Usage example with all constructor options (auth, expire_after, single_view) and error handling for requests.RequestException.

```python
import requests

uploader = ShareyUploader(
    Path("secret.png"),
    auth="beloved",
    expire_after="24h",
    single_view=True,
)
try:
    print(uploader.upload().strip())
except requests.RequestException as e:
    print(f"upload failed: {e}")
```

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

### Configuration management commands

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Shows commands for creating, inspecting, and using configuration files: --init-config, --show-config, --config, --no-config, and overriding config with CLI flags.

```sh
# Create a default configuration file at the default path
lain-upload --init-config

# Create a default configuration file at a custom path
lain-upload --init-config config.json

# Show the effective configuration (defaults merged with the default config file)
lain-upload --show-config

# Create a default configuration file at the default path and print it
lain-upload --init-config --show-config

# Create a default configuration file at a custom path and print it
lain-upload --init-config /path/to/config.json --show-config

# Show the effective configuration (defaults merged with the custom config file)
lain-upload --config config.json --show-config

# Upload using the config file's default_host (no --host needed)
lain-upload kuroneko.png

# Override the config file's default_host
lain-upload --host uguu shironeko.png

# Use a custom configuration file
lain-upload --config /path/to/config.json kamineko.png

# Ignore the configuration file and use only CLI flags
lain-upload --no-config kuroneko.png

# Override config's host and expiration (CLI flag overrides config)
lain-upload --host litterbox --expire-after 24h kuroneko.png
```

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

### lain-upload CLI options

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Lists all command-line options: --host, --auth, --expire-after, --long-filenames, --single-view, --config, --init-config, --show-config, --no-config, -h, -v. Default host is catbox.

```sh
    --host            HOST                  File hosting service to upload to (default: catbox)
    --auth            AUTH                  Authentication credentials for the host (format varies per host)
    --expire-after    DURATION              How long before the file expires when supported (e.g. 1h, 24h, 72h)
    --long-filenames  -                     Enable longer generated filenames when supported by the host
    --single-view     -                     Delete upload after it has been viewed once
    --config          PATH                  Path to a custom configuration file
    --init-config     [PATH]                Create a default configuration file at the default or given path
    --show-config     -                     Print the effective configuration after merging defaults and config file
    --no-config       -                     Ignore the configuration file and use only CLI flags
-h, --help            -                     Show help and exit
-v, --version         -                     Show version and exit
```

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

### WaifuVaultUploader basic usage example

Source: https://github.com/necraul/lain-upload

Basic usage: creates a WaifuVaultUploader with a file path and expiration, uploads, and prints the resulting URL.

```python
from pathlib import Path

from lain_upload.uploader import WaifuVaultUploader

url = WaifuVaultUploader(Path("kuroneko.png"), expire_after="24h").upload().strip()
print(url)  # https://waifuvault.moe/f/xxxx
```

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

### Basic ShareyUploader usage

Source: https://github.com/necraul/lain-upload

Basic usage example: creates a ShareyUploader with a file path and auth password, then uploads and strips the resulting URL.

```python
from pathlib import Path

from lain_upload.uploader import ShareyUploader

url = ShareyUploader(Path("kuroneko.png"), auth="beloved").upload().strip()
```

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

### Basic usage of TempDitchUploader

Source: https://github.com/necraul/lain-upload

Programmatic upload example. Creates a TempDitchUploader with a Path, calls upload(), strips whitespace, and prints the resulting URL. The CLI blocks this host, so this is for direct use only.

```python
from pathlib import Path

from lain_upload.uploader import TempDitchUploader

url = TempDitchUploader(Path("kuroneko.png")).upload().strip()
print(url)
```

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

### Upload files with lain-upload CLI

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Shows common upload commands: single file, multiple files, host selection, authentication, expiration, long filenames, single-view, password-protected uploads, all hosts, and help/version flags. Default host is catbox.

```sh
# Upload a single file (default host: catbox)
lain-upload kuroneko.png

# Upload multiple files from different directories
lain-upload /path/to/kuroneko.png /path/to/another/directory/shironeko.png yamineko.png ../kamineko.png

# Select a specific host
lain-upload --host uguu kuroneko.png

# Use host authentication when supported
lain-upload --host mixdrop --auth necraul@kuroneko.dev:generated_api_key kuroneko.png

# Set temporary file expiration when supported (e.g. 1h, 12h, 24h, 72h, etc.)
lain-upload --host litterbox --expire-after 24h kuroneko.png

# Enable longer generated filenames when supported
lain-upload --host 0x0 --long-filenames -- kuroneko.png shironeko.png

# Upload a file that is automatically deleted after the first view
lain-upload --host waifuvault --single-view yamineko.png

# Upload a file protected by a password required for access
lain-upload --host sharey --auth beloved kamineko.png

# Upload to every available non-deprecated host
lain-upload --host all kamineko.png

# Display help and version
lain-upload -h
lain-upload -v
```

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

### __version__

Source: https://github.com/necraul/lain-upload

Returns the installed package version as a string, or `"dev"` when run from an uninstalled source checkout. It never raises an exception.

```APIDOC
## __version__

### Description
Returns the distribution version (e.g. `"1.29"`) or `"dev"` when run from an uninstalled source checkout. Calls `importlib.metadata.version("lain_upload")`; `PackageNotFoundError` is caught internally.

### Return Type
- **str** - The distribution version or `"dev"`.

### Example
```python
from lain_upload import __version__
print(f"lain-upload {__version__}")
```
```

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

### Install lain-upload with pipx (isolated)

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Installs lain-upload in an isolated environment using pipx, which avoids dependency conflicts with other Python packages.

```sh
pipx install "lain-upload[clipboard]"
```

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

### Manual upload with curl -F

Source: https://github.com/necraul/lain-upload/blob/main/README.md

Shows the manual way to upload a file to a service that accepts multipart HTTP requests. Use this as a baseline for understanding what lain-upload automates.

```sh
curl -F "file=@kuroneko.png" https://example-upload-service.tld/upload-endpoint
```

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

### Usage pattern for CatboxUploader and LitterboxUploader

Source: https://github.com/necraul/lain-upload

Shows how to instantiate uploader classes with host-specific options and call upload() to get a public URL. CatboxUploader accepts an auth keyword; LitterboxUploader accepts expire_after and long_filenames.

```python
from pathlib import Path

from lain_upload.uploader import CatboxUploader, LitterboxUploader

url = CatboxUploader(Path("kuroneko.png"), auth="userhash").upload()
print(url)

url2 = LitterboxUploader(Path("shironeko.png"), expire_after="24h", long_filenames=True).upload()
```

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

### Basic usage example for FilesterUploader

Source: https://github.com/necraul/lain-upload

Uploads a file with an auth token and prints the resulting URL. The upload() method returns a string like https://filester.me/d/xxxx.

```python
from pathlib import Path

from lain_upload.uploader import FilesterUploader

url = FilesterUploader(Path("kuroneko.png"), auth="bearer-token").upload().strip()
print(url)  # https://filester.me/d/xxxx
```

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

### Uploader usage with full error handling

Source: https://github.com/necraul/lain-upload

Demonstrates handling the complete documented exception set when calling upload(): FileNotFoundError, ValueError, requests.RequestException, and (KeyError, IndexError, TypeError) for unexpected responses. Uses UguuUploader as an example.

```python
import requests

from lain_upload.uploader import UguuUploader

try:
    url = UguuUploader("/tmp/kuroneko.png").upload().strip()
except FileNotFoundError as e:
    print(f"no such file: {e}")
except ValueError as e:
    print(f"invalid input: {e}")
except requests.RequestException as e:
    print(f"network error: {e}")
except (KeyError, IndexError, TypeError) as e:
    print(f"unexpected response: {e}")
```

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

### Error handling example for FilesterUploader

Source: https://github.com/necraul/lain-upload

Shows how to catch network/HTTP errors (requests.RequestException) and malformed JSON responses (KeyError/TypeError). Without auth, no Authorization header is sent.

```python
import requests

try:
    FilesterUploader(Path("kuroneko.png")).upload()   # no auth -> no Authorization header
except requests.RequestException as e:
    print(f"network/HTTP: {e}")
except (KeyError, TypeError) as e:
    print(f"unexpected server response: {e}")
```

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

### Error handling example

Source: https://github.com/necraul/lain-upload

Catches network/HTTP errors and unexpected server responses (KeyError/TypeError) during upload.

```python
import requests

try:
    BuzzheavierUploader(Path("kuroneko.png")).upload()
except requests.RequestException as e:
    print(f"network/HTTP: {e}")
except (KeyError, TypeError) as e:
    print(f"unexpected server response: {e}")
```

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

### Basic FileDitch upload usage

Source: https://github.com/necraul/lain-upload

Uploads a file and prints the returned URL, which starts with https://itsfileditchfiles.st/.

```python
from pathlib import Path

from lain_upload.uploader import FileDitchUploader

url = FileDitchUploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://itsfileditchfiles.st/f/xxxx
```

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

### version.py: Resolve __version__ from importlib.metadata

Source: https://github.com/necraul/lain-upload

Module-level constant that resolves the installed distribution version via importlib.metadata.version("lain_upload"). Falls back to "dev" when PackageNotFoundError is raised (e.g., uninstalled source checkout). Resolved once at import time, stable for process lifetime.

```python
from importlib.metadata import PackageNotFoundError, version

try:
    __version__ = version("lain_upload")
except PackageNotFoundError:
    __version__ = "dev"
```

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

### Module entry point in __main__.py

Source: https://github.com/necraul/lain-upload

Runs the CLI main function and raises SystemExit with its return code when executed as a module.

```python
from lain_upload.cli import main

if __name__ == "__main__":
    raise SystemExit(main())
```

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

### PoneUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Initializes a PoneUploader instance with the file to upload. The file must exist and be at most 1 GiB in size.

```APIDOC
## Constructor

### Description
Initializes a PoneUploader instance with the file to upload.

### Method
Constructor

### Signature
`__init__(self, file_path)`

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 1 GiB).

### Usage Example
```python
from pathlib import Path
from lain_upload.uploader import PoneUploader

uploader = PoneUploader(Path("kuroneko.png"))
```
```

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

### main() function signature

Source: https://github.com/necraul/lain-upload

Exact signature of the CLI entry point. Takes no parameters and returns None implicitly on success; raises SystemExit via parser.error (exit 2) or sys.exit(1) when any upload failed.

```python
def main():
```

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

### GofileUploader.__init__

Source: https://github.com/necraul/lain-upload

Initializes a GofileUploader instance with the file to upload and an optional bearer token. The file must exist and be at most 100 GB.

```APIDOC
## GofileUploader.__init__

### Description
Initializes a GofileUploader instance with the file to upload and an optional bearer token. The file must exist and be at most 100 GB.

### Method
Constructor

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 100 GB).
- **auth** (`str`) - Optional - Gofile bearer API token. Falsy → no `Authorization` header is sent.

### Request Example
```python
GofileUploader(Path("kuroneko.png"), auth="bearer-token")
```
```

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

### MixdropUploader.__init__(file_path, auth="")

Source: https://github.com/necraul/lain-upload

Constructor for the MixdropUploader class. Initializes an uploader instance with the file path and authentication credentials in the format email:api_key.

```APIDOC
## MixdropUploader.__init__(file_path, auth="")

### Description
Constructor for the MixdropUploader class. Initializes an uploader instance with the file path and authentication credentials in the format email:api_key.

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 100 GB).
- **auth** (str) - Required (service requirement) - Credentials in the exact format `email:api_key`. Authentication is mandatory — `upload()` raises `ValueError` if `auth` does not contain a `:` separator.

### Usage Example
```python
from pathlib import Path

from lain_upload.uploader import MixdropUploader

url = MixdropUploader(
    Path("kuroneko.png"), auth="necraul@kuroneko.dev:generated_api_key"
).upload().strip()
print(url)  # https://mixdrop.top/f/xxxx
```
```

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

### UguuUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Constructor for the UguuUploader class. Initializes an uploader instance with the specified file path, which must exist and be at most 128 MiB.

```APIDOC
## Constructor

### Description
Initializes a new UguuUploader instance with the given file path.

### Method
Constructor

### Signature
`def __init__(self, file_path)`

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 128 MiB).

### Usage Example
```python
from pathlib import Path
from lain_upload.uploader import UguuUploader

uploader = UguuUploader(Path("kuroneko.png"))
```
```

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

### X0Uploader.__init__(file_path, long_filenames=False)

Source: https://github.com/necraul/lain-upload

Constructor for the X0Uploader class. Initializes an uploader for the x0.at host with the given file path and optional long filename support.

```APIDOC
## Constructor

### Description
Initializes an X0Uploader instance.

### Signature
```python
def __init__(self, file_path, long_filenames=False):
```

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 1 GiB).
- **long_filenames** (`bool`) - Optional (default `False`) - When `True`, sends `id_length=24` to request a 24-char filename; when `False`, no `id_length` field is sent.

```

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

### load_effective_config(path=None, no_config=False)

Source: https://github.com/necraul/lain-upload

Loads the effective configuration, optionally ignoring all files. Used by cli.main().

```APIDOC
## load_effective_config(path=None, no_config=False)

### Description
Loads the effective configuration, optionally ignoring all files. Used by cli.main().

### Method
Function call

### Endpoint
`load_effective_config(path=None, no_config=False)`

### Parameters
#### Path Parameters
- **path** (`str` | `os.PathLike` | `None`) - Optional - Explicit config path (passed through to `load_config`).
- **no_config** (`bool`) - Optional - When `True`, ignores all files and returns `copy.deepcopy(DEFAULT_CONFIG)`.

### Response
#### Success Response
- **Return type**: `dict` — effective configuration. Precedence within this function: `no_config=True` wins over an explicit path; otherwise the explicit path is used if given, else the default path.
- **Used by**: `cli.main()`.
```

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

### Direct uploader usage with CatboxUploader

Source: https://github.com/necraul/lain-upload

Shows the supported direct API usage: construct an uploader with a file path and call upload(). Prints the version and the returned URL. This is the same pattern the CLI itself uses.

```python
from lain_upload import __version__
from lain_upload.uploader import CatboxUploader

print(f"lain-upload {__version__}")

url = CatboxUploader("/tmp/kuroneko.png").upload()
print(url)
```

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

### Basic X0Uploader usage

Source: https://github.com/necraul/lain-upload

Uploads a file to x0.at and prints the returned URL.

```python
from pathlib import Path

from lain_upload.uploader import X0Uploader

url = X0Uploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://x0.at/xxxx
```

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

### Programmatic CLI invocation with custom argv

Source: https://github.com/necraul/lain-upload

Runs the CLI from Python by setting sys.argv and calling cli.main(). Returns None on success.

```python
import sys

from lain_upload import cli

# run the CLI programmatically with custom argv
sys.argv = ["lain-upload", "--host", "gofile", "--auth", "token", "a.png"]
code = cli.main()  # returns None on success
```

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

### NullUploader.__init__

Source: https://github.com/necraul/lain-upload

Constructor for the NullUploader class. Initializes an uploader instance for uploading files to 0x0.st with optional expiration and long filename settings.

```APIDOC
## NullUploader.__init__

### Description
Constructor for the NullUploader class. Initializes an uploader instance for uploading files to 0x0.st with optional expiration and long filename settings.

### Method
Constructor

### Signature
```python
def __init__(self, file_path, expire_after=None, long_filenames=False):
```

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 512 MiB).
- **expire_after** (str | None) - Optional - Expiration duration, format `\d+h`; `None`/falsy → no `expires` field is sent. Capped at 8760 hours (365 days).
- **long_filenames** (bool) - Optional - When `True`, sends an empty `secret` field to request a longer generated filename.

```

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

### CLI version flags: -v and --version

Source: https://github.com/necraul/lain-upload

Command-line invocations that print the version and exit 0. Both -v and --version are supported.

```sh
lain-upload -v      # prints the version and exits 0
lain-upload --version
```

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

### BuzzheavierUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Constructor for the BuzzheavierUploader class. Initializes the uploader with the file to upload, which must exist and be ≤ 100 GB.

```APIDOC
## Constructor

### Description
Initializes a new BuzzheavierUploader instance.

### Method
Constructor

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 100 GB). The filename is embedded in the endpoint URL.

### Usage Example
```python
from pathlib import Path
from lain_upload.uploader import BuzzheavierUploader

uploader = BuzzheavierUploader(Path("kuroneko.png"))
```
```

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

### PomfUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Constructor for the PomfUploader class. Initializes an uploader instance with the specified file path, which must exist and be at most 1 GiB in size.

```APIDOC
## Constructor

### Description
Initializes a PomfUploader instance with the given file path.

### Method
Constructor

### Signature
`def __init__(self, file_path)`

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 1 GiB).

### Notes
This host accepts no extra options.
```

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

### CatboxUploader.__init__(file_path, auth="")

Source: https://github.com/necraul/lain-upload

Constructor for the CatboxUploader class. Initializes the uploader with the file path and optional Catbox userhash for authentication.

```APIDOC
## CatboxUploader.__init__(file_path, auth="")

### Description
Constructor for the CatboxUploader class. Initializes the uploader with the file path and optional Catbox userhash for authentication.

### Method
Constructor

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 200 MB).
- **auth** (str) - Optional - Catbox userhash for user authentication.

### Response
No return value.
```

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

### Basic upload usage

Source: https://github.com/necraul/lain-upload

Uploads a file and prints the returned URL. The URL is stripped of whitespace.

```python
from pathlib import Path

from lain_upload.uploader import PoneUploader

url = PoneUploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://pone.rs/xxxx
```

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

### WaifuVaultUploader Constructor

Source: https://github.com/necraul/lain-upload

Creates a new WaifuVaultUploader instance for uploading files to waifuvault.moe. Accepts the file path and optional expiration, filename hiding, and single-view settings.

```APIDOC
## Constructor

### Description
Initializes a WaifuVaultUploader with the file to upload and optional parameters.

### Parameters
- `file_path` (pathlib.Path) - Required - File to upload (must exist, ≤ 2 GB).
- `expire_after` (str | None) - Optional - Expiration duration, format `\d+h`; capped at 8760 hours; `None`/falsy → no `expires` query param.
- `long_filenames` (bool) - Optional - When `True`, sends `hide_filename=true` (hidden original filename → generated id-based name).
- `single_view` (bool) - Optional - When `True`, sends `one_time_download=true` (burn after first view).

### Example
```python
from pathlib import Path
from lain_upload.uploader import WaifuVaultUploader

uploader = WaifuVaultUploader(Path("kuroneko.png"), expire_after="24h")
```
```

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

### get_host_options(cfg, host_name)

Source: https://github.com/necraul/lain-upload

Returns a shallow copy of the per-host configuration for the given host, with every value validated. The result is used as the base kwargs for the uploader constructor.

```APIDOC
## get_host_options(cfg, host_name)

### Description
Returns a shallow copy of the per-host configuration for the given host, with every value validated. The result is used as the base kwargs for the uploader constructor.

### Method
Function call

### Endpoint
`get_host_options(cfg, host_name)`

### Parameters
- **cfg** (`dict`) - Required - Effective configuration.
- **host_name** (`str`) - Required - Host key, e.g. `"catbox"`, `"litterbox"`.

### Response
#### Return Value
- **dict** - A shallow `.copy()` of `cfg["hosts"].get(host_name, {})` with every value passed through `validate_option`; result is used as the base `kwargs` for the uploader constructor.

### Throws
- `argparse.ArgumentTypeError` - If a configured `expire_after` fails `expire_after_type` validation.

### Request Example
```python
kwargs = get_host_options(cfg, "litterbox")
# {'expire_after': '12h', 'long_filenames': False}
```

### Error Example
```python
import argparse

try:
    get_host_options({"hosts": {"litterbox": {"expire_after": "1d"}}}, "litterbox")
except argparse.ArgumentTypeError as e:
    print(e)  # invalid format: '1d'. must be like '12h'.
```
```

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

### ShareyUploader.__init__

Source: https://github.com/necraul/lain-upload

Constructor for the ShareyUploader class. Initializes an uploader instance with the file path and optional parameters for authentication, expiration, and single-view mode.

```APIDOC
## Constructor

### Description
Initializes a ShareyUploader instance.

### Method
Constructor

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 100 GB).
- **auth** (str) - Optional - Upload password. Falsy → no `password` form field.
- **expire_after** (str) - Optional - Expiration, format `\d+h`, normalized to the supported set (`1h`, `24h`, `7d`/168h, `30d`/720h, `90d`/2160h) with rounding **down**; `None`/falsy → no `expiry` field.
- **single_view** (bool) - Optional - When `True`, sends `burn_after_view=true`.

### Example
```python
def __init__(self, file_path, auth="", expire_after="168h", single_view=False):
```
```

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

### LitterboxUploader.__init__

Source: https://github.com/necraul/lain-upload

Constructor for the LitterboxUploader class. Initializes an uploader for a file to be uploaded to litterbox.catbox.moe with optional expiration and filename length settings.

```APIDOC
## Constructor

### Signature
```python
def __init__(self, file_path, expire_after="12h", long_filenames=False):
```

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 1 GB).
- **expire_after** (`str`) - Optional, default `"12h"` - Requested expiration, format `\d+h`. Normalized down to the nearest supported value: `1h`, `12h`, `24h`, or `72h`.
- **long_filenames** (`bool`) - Optional, default `False` - Request 16-char generated filenames (`True`) vs 6-char (`False`).
```

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

### load_config(path=None)

Source: https://github.com/necraul/lain-upload

Loads the effective configuration from a file, merging with defaults. Returns a deep copy of DEFAULT_CONFIG if the file does not exist.

```APIDOC
## load_config(path=None)

### Description
Loads the effective configuration from a file, merging with defaults. Returns a deep copy of DEFAULT_CONFIG if the file does not exist.

### Method
Function call

### Endpoint
`load_config(path=None)`

### Parameters
#### Path Parameters
- **path** (`str` | `os.PathLike` | `None`) - Optional - Explicit config file path. `None` → `get_default_config_path()`. Relative paths are `expanduser()`-expanded.

### Response
#### Success Response
- **Return type**: `dict` — effective configuration.
- **Behavior**: if the file does not exist, returns `copy.deepcopy(DEFAULT_CONFIG)`. Otherwise reads the file as UTF-8 JSON and returns `merge_config(DEFAULT_CONFIG, user_cfg)` (deep merge, so omitted keys keep defaults).
- **Throws**: `json.JSONDecodeError` (subclass of `ValueError`) when the file exists but contains invalid JSON; `OSError` on read errors.
```

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

### Basic GofileUploader usage

Source: https://github.com/necraul/lain-upload

Uploads a file with auth token and prints the returned URL.

```python
from pathlib import Path

from lain_upload.uploader import GofileUploader

url = GofileUploader(Path("kuroneko.png"), auth="bearer-token").upload().strip()
print(url)  # https://gofile.io/d/xxxx
```

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

### CLI usage with error handling

Source: https://github.com/necraul/lain-upload

Shows a successful upload to litterbox with --expire-after, then a failing upload. Success prints the URL to stdout; failures print to stderr and set exit status to 1.

```sh
lain-upload --host litterbox --expire-after 12h kuroneko.png
# prints to stdout:  kuroneko.png: https://litter.catbox.moe/xxxxxx
# upload failures are printed to stderr and exit status becomes 1
lain-upload missing.png; echo "exit=$?"
# File not found: missing.png (stderr), exit=1
```

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

### Build headers with Basic auth

Source: https://github.com/necraul/lain-upload

Builds the Authorization header using HTTP Basic auth with an empty username and the API key as the password. Returns an empty dict if no auth is provided.

```python
def _build_headers(self):
    if not self.auth:
        return {}

    token = base64.b64encode(f":{self.auth}".encode()).decode()
    return {"Authorization": f"Basic {token}"}
```

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

### Default configuration document (DEFAULT_CONFIG)

Source: https://github.com/necraul/lain-upload

Exact contents of DEFAULT_CONFIG, written verbatim by --init-config and used as the merge base for all loads. Located at src/lain_upload/config.py:12-40.

```json
{
  "default_host": "catbox",
  "hosts": {
    "catbox": {"auth": null},
    "litterbox": {"expire_after": "12h", "long_filenames": false},
    "pomf": {},
    "uguu": {},
    "pone": {},
    "fileditch": {},
    "tempditch": {},
    "0x0": {"expire_after": null, "long_filenames": false},
    "x0": {},
    "waifuvault": {"expire_after": "12h", "long_filenames": false, "single_view": false},
    "gofile": {"auth": null},
    "pixeldrain": {"auth": null},
    "buzzheavier": {},
    "mixdrop": {"auth": null},
    "sharey": {"auth": null, "expire_after": "168h", "single_view": false},
    "filester": {"auth": null}
  }
}
```

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

### save_config(cfg, path=None)

Source: https://github.com/necraul/lain-upload

Serializes a configuration document to a JSON file, creating parent directories as needed. Returns the absolute path written.

```APIDOC
## save_config(cfg, path=None)

### Description
Serializes a configuration document to a JSON file, creating parent directories as needed. Returns the absolute path written.

### Method
Function call

### Endpoint
`save_config(cfg, path=None)`

### Parameters
#### Path Parameters
- **cfg** (`dict`) - Required - Configuration document to serialize (`DEFAULT_CONFIG` is passed by the CLI).
- **path** (`str` | `os.PathLike` | `None`) - Optional - Destination path; `None` → default path. `expanduser()`-expanded.

### Response
#### Success Response
- **Return type**: `pathlib.Path` — the absolute path the file was written to (`path.absolute()`).
- **Behavior**: creates parent directories with `mkdir(parents=True, exist_ok=True)`, writes the config as indented JSON (`json.dump(cfg, f, indent=2)`) plus a trailing newline, UTF-8.
- **Throws**: `OSError` on filesystem errors.
```

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

### FileDitchUploader constructor

Source: https://github.com/necraul/lain-upload

Initializes the uploader with a file path. The file must exist and be ≤ 150 GB. No extra options are accepted.

```python
def __init__(self, file_path):
```

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

### X0Uploader constructor

Source: https://github.com/necraul/lain-upload

Initializes an X0Uploader instance with a file path and optional long filenames flag.

```python
def __init__(self, file_path, long_filenames=False):
```

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

### FileDitchUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Constructor for the FileDitchUploader class. Initializes an uploader instance for uploading a file to new.fileditch.com. The file must exist and be at most 150 GB.

```APIDOC
## FileDitchUploader.__init__(file_path)

### Description
Constructor for the FileDitchUploader class. Initializes an uploader instance for uploading a file to new.fileditch.com. The file must exist and be at most 150 GB.

### Method
Constructor

### Signature
```python
def __init__(self, file_path):
```

### Parameters
- **file_path** (`pathlib.Path`) - Required - File to upload (must exist, ≤ 150 GB).

### Notes
This host accepts no extra options.
```

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

### Basic CatboxUploader usage

Source: https://github.com/necraul/lain-upload

Uploads a file with an optional userhash and prints the returned URL. The URL may contain trailing whitespace, so .strip() is used.

```python
from pathlib import Path

from lain_upload.uploader import CatboxUploader

url = CatboxUploader(Path("kuroneko.png"), auth="my_userhash").upload().strip()
print(url)  # https://files.catbox.moe/abcd1234.png
```

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

### X0Uploader.upload()

Source: https://github.com/necraul/lain-upload

Uploads the file to x0.at and returns the resulting URL as a string. Inherited from BaseUploader. Throws standard errors on failure.

```APIDOC
## Method: upload()

### Description
Uploads the file to the x0.at host and returns the plain-text URL from the response.

### Return Type
`str` - e.g., `https://x0.at/xxxx`

### Throws
- `FileNotFoundError` - missing file
- `ValueError` - file > 1 GiB
- `requests.RequestException` - network/HTTP
- `KeyError`/`IndexError`/`TypeError` - unexpected response

### Request Example
```python
from pathlib import Path

from lain_upload.uploader import X0Uploader

url = X0Uploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://x0.at/xxxx
```

### Response Example
```
https://x0.at/xxxx
```

```

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

### Basic usage of PomfUploader

Source: https://github.com/necraul/lain-upload

Uploads a file and prints the returned URL. The upload() method returns a string like https://pomf2.lain.la/f/xxxx.

```python
from pathlib import Path

from lain_upload.uploader import PomfUploader

url = PomfUploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://pomf2.lain.la/f/xxxx
```

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

### WaifuVaultUploader all options with error handling

Source: https://github.com/necraul/lain-upload

Shows using all constructor options (expire_after, long_filenames, single_view) and handling requests.RequestException during upload.

```python
import requests

uploader = WaifuVaultUploader(
    Path("secret.png"),
    expire_after="12h",
    long_filenames=True,   # hide_filename=true
    single_view=True,      # one_time_download=true
)
try:
    print(uploader.upload().strip())
except requests.RequestException as e:
    print(f"upload failed: {e}")
```

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

### CatboxUploader.upload()

Source: https://github.com/necraul/lain-upload

Uploads a file to Catbox and returns the resulting URL. This is a direct use of the uploader class, as the CLI does.

```APIDOC
## CatboxUploader.upload()

### Description
Uploads a file to Catbox and returns the resulting URL. This is a direct use of the uploader class, as the CLI does.

### Method
`upload()`

### Parameters
- **file_path** (str) - Required - Path to the file to upload.

### Returns
- **str** - The URL of the uploaded file.

### Request Example
```python
from lain_upload.uploader import CatboxUploader
url = CatboxUploader("/tmp/kuroneko.png").upload()
print(url)
```
```

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

### LitterboxUploader with options and error handling

Source: https://github.com/necraul/lain-upload

Demonstrates using long_filenames=True and an unsupported expire_after='5h' (rounds down to 1h with a stderr warning), plus catching requests.RequestException during upload.

```python
import requests

uploader = LitterboxUploader(
    Path("shironeko.png"),
    expire_after="5h",          # not supported -> rounds down to 1h, warning on stderr
    long_filenames=True,        # fileNameLength=16
)
try:
    print(uploader.upload().strip())  # https://litter.catbox.moe/xxxxxxxxxxxxx
except requests.RequestException as e:
    print(f"upload failed: {e}")
```

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

### WaifuVaultUploader query parameters building

Source: https://github.com/necraul/lain-upload

Builds query parameters for the upload request. Adds expires, hide_filename, and one_time_download based on constructor options.

```python
params = {}
if self.expire_after:
    params["expires"] = self._normalize_expire_after(self.expire_after)
if self.long_filenames:
    params["hide_filename"] = "true"
if self.single_view:
    params["one_time_download"] = "true"
```

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

### NullUploader constructor signature

Source: https://github.com/necraul/lain-upload

Constructor for NullUploader. file_path must exist and be ≤ 512 MiB. expire_after is a string in \d+h format, capped at 8760 hours; None means no expires field. long_filenames=True sends an empty secret field for a longer filename.

```python
def __init__(self, file_path, expire_after=None, long_filenames=False):
```

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

### Basic UguuUploader usage

Source: https://github.com/necraul/lain-upload

Uploads a file and prints the returned URL. The response is stripped of surrounding whitespace.

```python
from pathlib import Path

from lain_upload.uploader import UguuUploader

url = UguuUploader(Path("kuroneko.png")).upload().strip()
print(url)  # https://uguu.se/xxxx
```

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

### Basic NullUploader usage

Source: https://github.com/necraul/lain-upload

Uploads a file to 0x0.st with an expiration of 72 hours and long filenames enabled, then prints the returned URL.

```python
from pathlib import Path

from lain_upload.uploader import NullUploader

url = NullUploader(Path("kuroneko.png"), expire_after="72h", long_filenames=True).upload().strip()
print(url)  # https://0x0.st/xxxx
```

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

### upload()

Source: https://github.com/necraul/lain-upload

Uploads the file to waifuvault.moe and returns the URL of the uploaded file. Inherited from BaseUploader.

```APIDOC
## upload()

### Description
Uploads the file to waifuvault.moe and returns the URL of the uploaded file. Inherited from BaseUploader.

### Return Type
`str` - The URL of the uploaded file, e.g. `https://waifuvault.moe/f/xxxx`.

### Throws
- `FileNotFoundError` - If the file does not exist.
- `ValueError` - If the file is larger than 2 GB.
- `requests.RequestException` - On network or HTTP errors.
- `KeyError`/`TypeError` - If the response JSON is malformed.

### Example
```python
from pathlib import Path
from lain_upload.uploader import WaifuVaultUploader

url = WaifuVaultUploader(Path("kuroneko.png"), expire_after="24h").upload().strip()
print(url)  # https://waifuvault.moe/f/xxxx
```
```

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

### get_host_options function signature

Source: https://github.com/necraul/lain-upload

Returns a shallow copy of the host configuration with each value passed through validate_option. Used as base kwargs for the uploader constructor. Throws argparse.ArgumentTypeError if a configured expire_after fails validation.

```python
def get_host_options(cfg, host_name):
```

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

### Programmatic access to __version__

Source: https://github.com/necraul/lain-upload

Import and print __version__ from lain_upload.version. Outputs e.g. "1.29" or "dev" in an uninstalled checkout.

```python
from lain_upload.version import __version__

print(__version__)  # e.g. "1.29", or "dev" in an uninstalled checkout
```

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

### TempDitchUploader.__init__(file_path)

Source: https://github.com/necraul/lain-upload

Constructor for the TempDitchUploader class. Initializes an uploader instance for the temp.fileditch.com service, which is deprecated and not selectable via the CLI but still usable programmatically. Accepts a file path to upload, with a maximum file size of 150 GB.

```APIDOC
## TempDitchUploader.__init__(file_path)

### Description
Constructor for the TempDitchUploader class. Initializes an uploader instance for the temp.fileditch.com service, which is deprecated and not selectable via the CLI but still usable programmatically. Accepts a file path to upload, with a maximum file size of 150 GB.

### Method
Constructor

### Parameters
- **file_path** (pathlib.Path) - Required - File to upload (must exist, ≤ 150 GB).

### Notes
- This host accepts no extra options.
- The `tempditch` host is deprecated and listed in `lain_upload.cli.deprecated_hosts`; the CLI refuses to select it and the `all` host expansion excludes it.
```

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

### WaifuVaultUploader constructor signature

Source: https://github.com/necraul/lain-upload

Constructor for WaifuVaultUploader. Accepts file_path (required), and optional expire_after, long_filenames, single_view parameters.

```python
def __init__(
    self, file_path, expire_after=None, long_filenames=False, single_view=False
):
```

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

### _progress_callback(bytes_sent, total_bytes)

Source: https://github.com/necraul/lain-upload

Prints an in-place progress bar to `sys.stderr` during upload. It is private but documented for subclass authors.

```APIDOC
## _progress_callback(bytes_sent, total_bytes)

### Description
Prints an in-place progress bar to `sys.stderr` during upload. It is private but documented for subclass authors.

### Method
_progress_callback(bytes_sent, total_bytes)

### Endpoint
N/A (method on uploader class)

### Parameters
- **bytes_sent** (int) - Required - Number of bytes sent so far.
- **total_bytes** (int) - Required - Total number of bytes to send.

### Response
No return value.
```

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

### upload() method signature

Source: https://github.com/necraul/lain-upload

Public method that runs the upload pipeline: validates the file, builds headers and parameters, sends the request, and returns the public URL via _extract_url. Throws FileNotFoundError, ValueError, requests.RequestException, or parsing errors as documented.

```python
def upload(self):
```

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

### NullUploader class declaration

Source: https://github.com/necraul/lain-upload

Declares the NullUploader class, which extends BaseUploader and uploads files to 0x0.st. The CLI host name is 0x0.

```python
class NullUploader(BaseUploader):
```
Tokens:
Raw