Metadata-Version: 2.4
Name: pyepp
Version: 0.6.1
Summary: A Python API on top of the EPP protocol.
Author-email: InternetNZ <ehsan@internetnz.net.nz>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/InternetNZ/pyepp
Project-URL: Repository, https://github.com/InternetNZ/pyepp
Project-URL: Documentation, https://pyepp.readthedocs.io/en/latest/index.html
Keywords: epp,registry,api,domain,nameserver
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1.6
Requires-Dist: lxml>=6.1.3
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: click>=8.5.0
Requires-Dist: markupsafe>=2.1.1
Provides-Extra: dev
Requires-Dist: bandit; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: safety; extra == "dev"
Dynamic: license-file

# PyEPP
>
> A Python API on top of the EPP protocol and an EPP CLI client to work easier with registry systems.

This is a Python API on [EPP](https://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol) protocol to connect to
any registry systems that support EPP and work with it. Also, it is a CLI client to interact with the registry systems.
It supports bellow RFCs:

- [RFC 5730 - Extensible Provisioning Protocol](https://datatracker.ietf.org/doc/html/rfc5730)
- [RFC 5731 - Domain Name Mapping](https://datatracker.ietf.org/doc/html/rfc5731)
- [RFC 5732 - Host Mapping](https://datatracker.ietf.org/doc/html/rfc5732)
- [RFC 5733 - Contact Mapping](https://datatracker.ietf.org/doc/html/rfc5733)
- [RFC 5734 - Transport over TCP](https://datatracker.ietf.org/doc/html/rfc5734)

## Installation

```sh
pip install pyepp
```

## Usage example

```python
from datetime import date

from pyepp import EppCommunicator
from pyepp.domain import Domain, DomainData, DSRecordData, DNSSECAlgorithm, DigestTypeEnum
from pyepp.contact import Contact, ContactData, PostalInfoData, AddressData

# client_cert and client_key may be omitted where
# a registry does not require certificate based authentication
config = {
    "server": "epp.test.net.nz",
    "port": "700",
    "client_cert": "/PATH/TO/YOUR/CLIENT_CERTIFICATE.crt",
    "client_key": "/PATH/TO/YOUR/CLIENT_KEY.pem"
}

# Using the Pythonic context manager (recommended, handles connect, login, logout, and cleanup):
with EppCommunicator(**config, user="user_name", password="password") as epp:
    hello = epp.hello()
    contact = Contact(epp)
    contact_check = contact.check(['contact-1', 'contact-2'])

# Or using Configuration Profiles (AWS CLI style, loaded from ~/.pyepp/config.ini):
with EppCommunicator.from_profile("ote") as epp:
    contact = Contact(epp)
    contact_check = contact.check(['contact-1', 'contact-2'])

# Or using manual sequence management:
epp = EppCommunicator(**config)

connect = epp.connect()
login = epp.login("user_name", "password")
# Sends a hello request and receive greeting in respond
hello = epp.hello()

contact = Contact(epp)

# Check contacts availability
contact_check = contact.check(['contact-1', 'contact-2'])

# Create a new contact
contact_create_params = ContactData(
    id='contact-1',
    email='epp@example.net.nz',
    postal_info=PostalInfoData(
        name='Registrar 1',
        organization='Registrar 1',
        address=AddressData(
            street_1='18 Registrar Street',
            street_2='Registrar CBD',
            city='Registrar',
            country_code='NZ',
            province='Registrar',
            postal_code='6011'
        ),
    ),
    phone='+64.111111111'
)
contact_create = contact.create(contact_create_params)

# Get contact details
contact_info = contact.info('contact-1')

domain = Domain(epp)
# Check domains availability
domain_check = domain.check(['domain1.nz', 'domain2.nz'])

# Create a new domain name
domain_create_params = DomainData(
    domain_name='example.nz',
    registrant='contact-1',
    admin='contact-1',
    tech='contact-1',
    billing='contact-3',
    period=3,
    host=['01y.test-indwrx2vkicn2otgm3otav5wpnzvjd.co.nz', '0d9x6239.example.co.nz'],
    dns_sec=DSRecordData(
        key_tag=1235,
        algorithm=DNSSECAlgorithm.DSA_SHA_1.value,
        digest_type=DigestTypeEnum.SHA_1.value,
        digest='8cdb09364147aed879d12c68d615f98af5900b73'
    ),
)
domain_create = domain.create(domain_create_params)

# Renew a domain name
renew_domain = domain.renew(domain_name='example-1.nz', expiry_date=date(2024, 2, 23), period=2)
```

## PyEPP CLI

PyEPP also has a command line interface that allows the user to interact with the registry system.

```text
Usage: pyepp [OPTIONS] COMMAND [ARGS]...

  A command line interface to work with PyEpp library.

Options:
  -p, --profile TEXT              Configuration profile name from config.ini
                                  (e.g. ote, prod).
  -c, --config-file PATH          Explicit path to config.ini file.
  --server TEXT
  --port TEXT
  --user TEXT
  --password TEXT
  --client-cert TEXT
  --client-key TEXT
  --extension TEXT                The extension to be loaded for the EPP
                                  command.
  -o, --output-format [XML|OBJECT|MIN|TABLE]
                                  [default: XML]
  --no-pretty
  --dry-run
  -f, --file FILENAME             If provided, the output will be written in
                                  the file.
  -v, --verbose
  -d, --debug
  --version                       Show the version and exit.
  -h, --help                      Show this message and exit.

Commands:
  contact  To work with Contact objects in the registry.
  domain   To work with Domain name objects in the registry.
  hello    Sends a hello command to the server and receives the Greeting...
  host     To work with Host objects in the registry.
  poll     To manage registry service messages.
  profile  Manage and inspect EPP configuration profiles.
  run      Receive an XML file containing an EPP XML command and execute it.
  shell    Start an interactive PyEPP shell session with persistent...
```

### Configuration Profiles (`~/.pyepp/config.ini`)

PyEPP supports user-defined configuration profiles (similar to AWS CLI profiles). Settings defined in `[default]` are shared globally and inherited by named profile sections (`[profile <name>]` or `[<name>]`):

```ini
[default]
port = 700
output_format = TABLE
no_pretty = false
dry_run = false

[profile ote]
server = epp.ote.registry.net.nz
user = test_registrar
password = secret_ote_pass
extensions = urn:ietf:params:xml:ns:secDNS-1.1

[profile prod]
server = epp.registry.net.nz
user = prod_registrar
password = secret_prod_pass
client_cert = ~/.pyepp/certs/client.crt
client_key = ~/.pyepp/certs/client.key
extensions = urn:ietf:params:xml:ns:secDNS-1.1
```

Using profiles with the CLI:

```sh
# List all configured profiles
pyepp profile list

# Show details of a profile (passwords masked by default)
pyepp profile show ote
pyepp profile show ote --show-secrets

# Run commands using a profile without needing --server, --user, or --password flags
pyepp -p ote domain check example.nz
```

### Interactive Shell (`pyepp shell`)

PyEPP provides an interactive REPL shell (`pyepp shell`) that connects and authenticates once, reusing the persistent TLS/TCP session across all commands without reconnecting on every invocation.

Key features include:

- **Pinned Bottom Dock & Scrollable Viewport**: Keeps the `pyepp> ` input prompt and live status bar docked to the bottom rows of the terminal, while command outputs scroll smoothly in the upper terminal region with full native scrollback preservation (`DECSTBM`).
- **Live Status Bar**: Displays real-time connection state (`● connected`, `○ disconnected`, `● dry-run`), active profile, `user@server:port`, output format, pretty-print mode, pending poll queue count (`✉ poll: <N>`), and round-trip execution latency (`last: <N>ms`).
- **Interactive Tab Auto-Completion**: Readline Tab and double-Tab auto-completion for commands, subcommands, profile names, flags, and options rendered cleanly above the dock.
- **Prefix History Search**: Up and Down arrow keys filter command history matching the currently typed prefix. History is persisted across sessions in `~/.pyepp/history` with automatic password scrubbing.
- **Mid-Session Profile Switching**: Switch registry endpoints on the fly using `use <profile>` or `profile use <profile>`.
- **Runtime Session Settings**: Adjust active settings dynamically using `set output-format <XML|OBJECT|MIN|TABLE>`, `set pretty <on|off>`, `set dry-run <on|off>`, `set debug <on|off>`, and `unset <debug|dry-run|pretty>`.
- **Response Inspection & File Export**: Re-render the last response without re-querying using `last [FORMAT]`, or save it to disk using `save <filepath> [FORMAT]`.
- **Session Control**: `status` (or `st`) for diagnostics, `reconnect` to re-authenticate, `clear` to clear the screen, and `exit` / `quit` / `q` to quit.

```sh
# Start interactive shell using a profile
pyepp -p ote shell

# Or connect in dry-run mode
pyepp -p ote --dry-run shell
```

### Enable shell autocomplete

To enable shell autocompletion for your shell follow the below commands:

#### Zsh

```sh
mkdir -p ~/.pyepp
_PYEPP_COMPLETE=zsh_source pyepp > ~/.pyepp/shell-complete.zsh
```

Source the file in `~/.zshrc`.

```sh
. ~/.pyepp/shell-complete.zsh
```

#### Bash

```sh
mkdir -p ~/.pyepp
_PYEPP_COMPLETE=bash_source pyepp > ~/.pyepp/shell-complete.bash
```

Source the file in `~/.bashrc`.

```sh
. ~/.pyepp/shell-complete.bash
```

## Development setup

Clone this project. It's recommended to create virtual environment. Then install the dependencies and
development dependencies:

```shell
pip install -r requirements.txt
pip install -r requirements.dev.txt
```

Before creating any pull requests please make sure your code lints and there is no security issues in your code
by running below scripts:

```shell
./scripts/linter.sh
./scripts/code-security-check.sh
```

Happy developing!

## Contributing

Please refer to [CONTRIBUTING.md](CONTRIBUTING.md)

<!-- Markdown link & img dfn's -->
