Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: flake8
name: ruff

on:
pull_request:
Expand All @@ -10,14 +10,13 @@ jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python 3.11
uses: actions/setup-python@v3
- uses: actions/checkout@v4
with:
python-version: 3.11
- name: Install dependencies
fetch-depth: 0
- uses: astral-sh/ruff-action@v4.1.0
- name: Check formatting of changed and new files
env:
BASE: ${{ github.base_ref }}
run: |
python -m pip install --upgrade pip
pip install flake8
- name: Analyze the code with flake8
run: flake8 .
git diff -z --name-only --diff-filter=ACMR "origin/$BASE...HEAD" -- '*.py' '*.pyi' '*.md' \
| xargs -0 -r ruff format --check --diff
29 changes: 17 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,25 +136,30 @@ The TrueNAS API client can also be used in Python scripts.
from truenas_api_client import Client

with Client() as c:
user = {"full_name": "John Doe", "username": "jdoe", "password": "Canary", "group_create": True}
new_user_entry = c.call("user.create", user)
print(new_user_entry["full_name"]) # John Doe
user = {
"full_name": "John Doe",
"username": "jdoe",
"password": "Canary",
"group_create": True,
}
new_user_entry = c.call("user.create", user)
print(new_user_entry["full_name"]) # John Doe
```

#### Login with a user account or an API key

```python
# User account
with Client(uri="ws://some.other.truenas/api/current") as c:
c.login_with_password(username, password)
c.login_with_password(username, password)

# API key
with Client(uri="ws://some.other.truenas/api/current") as c:
c.login_with_api_key(username, key)
c.login_with_api_key(username, key)

# API key file
with Client(uri="ws://some.other.truenas/api/current") as c:
c.login_with_api_key(username, "/path/to/keyfile.json")
c.login_with_api_key(username, "/path/to/keyfile.json")
```

API-key login uses **SCRAM-SHA-512** by default (TrueNAS 26 and later), which never transmits
Expand All @@ -167,7 +172,7 @@ otherwise strip SCRAM to force the client to divulge the cleartext key:
from truenas_api_client import APIKeyAuthMech

with Client(uri="ws://old.truenas/api/current") as c:
c.login_with_api_key(username, key, auth_mechanism=APIKeyAuthMech.PLAIN)
c.login_with_api_key(username, key, auth_mechanism=APIKeyAuthMech.PLAIN)
```

The `midclt` CLI exposes this as `--plain`. **Warning:** PLAIN transmits the raw API key; only
Expand All @@ -189,7 +194,7 @@ Pass `channel_binding=False` to authenticate without it:
```python
# Reach a server without channel-binding support, or a plain ws:// endpoint
with Client(uri="wss://some.other.truenas/api/current") as c:
c.login_with_api_key(username, key, channel_binding=False)
c.login_with_api_key(username, key, channel_binding=False)
```

The `midclt` CLI exposes the same override as `--no-channel-binding`.
Expand Down Expand Up @@ -252,10 +257,10 @@ For single-section files, any section name is accepted. Files without section he

```python
with Client() as c:
is_locked = c.call("pool.dataset.lock", "mypool/mydataset", job=True)
if is_locked:
args = {"datasets": [{"name": "mypool/mydataset", "passphrase": "passphrase"}]}
c.call("pool.dataset.unlock", "mypool/mydataset", args, job=True)
is_locked = c.call("pool.dataset.lock", "mypool/mydataset", job=True)
if is_locked:
args = {"datasets": [{"name": "mypool/mydataset", "passphrase": "passphrase"}]}
c.call("pool.dataset.unlock", "mypool/mydataset", args, job=True)
```

## API Rate Limits
Expand Down
9 changes: 4 additions & 5 deletions examples/create_smb_time_machine_share.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,7 @@
ds = c.call("pool.dataset.create", {"name": DS_NAME, "share_type": "SMB"})

# Create the actual SMB share for time machine purposes
c.call("sharing.smb.create", {
"path": ds["mountpoint"],
"name": SHARE_NAME,
"purpose": "TIMEMACHINE"
})
c.call(
"sharing.smb.create",
{"path": ds["mountpoint"], "name": SHARE_NAME, "purpose": "TIMEMACHINE"},
)
23 changes: 11 additions & 12 deletions examples/two_factor_challenge_response_auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@


def get_totp_secret() -> str:
""" This assumes the TOTP secret is written somewhere on client """
with open(TOTP_FILE, 'r') as f:
"""This assumes the TOTP secret is written somewhere on client"""
with open(TOTP_FILE, "r") as f:
return f.read()


Expand All @@ -28,11 +28,10 @@ def get_2fa_token(secret: str) -> str:


def authenticate_client(c: truenas_api_client.Client) -> bool:
resp = c.call("auth.login_ex", {
"mechanism": "PASSWORD_PLAIN",
"username": USERNAME,
"password": PASSWORD
})
resp = c.call(
"auth.login_ex",
{"mechanism": "PASSWORD_PLAIN", "username": USERNAME, "password": PASSWORD},
)

match resp["response_type"]:
case "SUCCESS":
Expand All @@ -51,17 +50,17 @@ def authenticate_client(c: truenas_api_client.Client) -> bool:
else:
otp_token = get_2fa_token(secret)

resp = c.call("auth.login_ex_continue", {
"mechanism": "OTP_TOKEN",
"otp_token": otp_token
})
resp = c.call(
"auth.login_ex_continue",
{"mechanism": "OTP_TOKEN", "otp_token": otp_token},
)

# For interactive session the `auth.login_ex_continue` may
# reply with OTP_REQUIRED again if the user fat-fingered input
# since this is machine input no amount of attempts will succeed
return resp["response_type"] == "SUCCESS"
case _:
raise ValueError(f'{resp["response_type"]}: Unexpected response type')
raise ValueError(f"{resp['response_type']}: Unexpected response type")


if not interactive:
Expand Down
7 changes: 7 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,10 @@ include = ["truenas_api_client*"]

[tool.mypy]
check_untyped_defs = true

[tool.ruff.lint]
select = ["E", "W", "F"]
ignore = ["F403", "F405"]

[tool.ruff.lint.pycodestyle]
max-line-length = 120
Loading
Loading