ksef2.profiles

Public helpers for local ksef2-cli compatible profiles.

Classes

CliProfileConfig

Import: from ksef2.profiles import CliProfileConfig

class CliProfileConfig(BaseModel)

Contents of the ksef2-cli config file: profiles and the active profile name.

Attributes

• active_profile: str | None — Name of the profile used when none is selected; None when no profile is active.
• profiles: dict[str, ProfileConfig] — Profiles keyed by name.

ProfileAuthConfig

Import: from ksef2.profiles import ProfileAuthConfig

class ProfileAuthConfig(BaseModel)

Authentication settings of a profile.

Which fields are required depends on type: token profiles need token_env, PEM XAdES profiles need cert and key, and PKCS#12 profiles need p12. Secrets are never stored; the *_env fields name the environment variables that hold them.

Attributes

• type: ProfileAuthType — Authentication method.
• token_env: str | None — Name of the environment variable holding the KSeF token.
• context_type: ContextIdentifierTypeEnum | ContextIdentifierType | None — Kind of context identifier for token authentication; defaults to nip.
• cert: str | Path | None — Path to the PEM certificate for XAdES authentication.
• key: str | Path | None — Path to the PEM private key for XAdES authentication.
• key_password_env: str | None — Name of the environment variable holding the password of an encrypted PEM key.
• p12: str | Path | None — Path to the PKCS#12/PFX archive for XAdES authentication.
• p12_password_env: str | None — Name of the environment variable holding the PKCS#12/PFX archive password.

ProfileConfig

Import: from ksef2.profiles import ProfileConfig

class ProfileConfig(BaseModel)

One named profile: environment, NIP and authentication settings.

Profiles are shared with ksef2-cli, so both read the same config file.

Deprecated

The flat auth_timeout key written by ksef2-cli 0.0.2 may be removed no earlier than ksef2 2.0.0; use max_poll_attempts and optionally poll_interval instead.

Attributes

• environment: ProfileEnvironment | Environment — Environment the profile targets; Environment values are normalized to their profile names.
• nip: str — NIP of the context to authenticate in.
• auth: ProfileAuthConfig — Authentication settings.
• poll_interval: float | None — Delay in seconds between authentication status checks (at least 0.1); None for the default.
• max_poll_attempts: int | None — Maximum number of authentication status checks (at least 1); None for the default.

Methods

ProfileConfig.sdk_environment (property)

sdk_environment: Environment

Return the profile environment as an SDK Environment.

Returns

• Environment — The matching Environment value.

ProfileStore

Import: from ksef2.profiles import ProfileStore

class ProfileStore

ProfileStore(path: str | Path | None = None)

Read and write local profiles compatible with ksef2-cli.

Attributes

• path

Methods

ProfileStore.default

@classmethod
def default() -> Self

Create a store at the default config location.

Returns

• Self — A store reading and writing KSEF2_CONFIG, or the default ksef2 config file.

ProfileStore.load

def load() -> CliProfileConfig

Read the config file.

Returns

• CliProfileConfig — The parsed config; empty when the file does not exist.

Raises

• KSeFValidationError — If the file is not valid TOML or does not match the profile schema.

ProfileStore.save

def save(
    name: str,
    profile: ProfileConfig,
    *,
    activate: bool = True,
    overwrite: bool = False,
) -> ProfileConfig

Add or replace a profile and write the config file.

Parameters

• name (str) — Name of the profile.
• profile (ProfileConfig) — Profile to store.
• activate (bool) — Whether to make it the active profile.
• overwrite (bool) — Whether to replace an existing profile with the same name.

Returns

• ProfileConfig — The stored profile.

Raises

• KSeFValidationError — If the profile exists and overwrite is false, or the file cannot be read or written.

ProfileStore.get

def get(name: str) -> ProfileConfig

Look up a profile by name.

Parameters

• name (str) — Name of the profile.

Returns

• ProfileConfig — The profile.

Raises

• KSeFValidationError — If the profile is not defined.

ProfileStore.list

def list() -> dict[str, ProfileConfig]

List all profiles.

Returns

• dict[str, ProfileConfig] — A copy of the profile mapping, keyed by name.

ProfileStore.current

def current() -> tuple[str, ProfileConfig] | None

Return the active profile.

Returns

• tuple[str, ProfileConfig] | None — The active profile's name and settings, or None when no profile is active.

ProfileStore.use

def use(name: str) -> ProfileConfig

Make a profile the active one.

Parameters

• name (str) — Name of the profile.

Returns

• ProfileConfig — The newly active profile.

Raises

• KSeFValidationError — If the profile is not defined.

ProfileStore.delete

def delete(name: str) -> ProfileConfig

Remove a profile.

If it was the active profile, no profile is active afterwards.

Parameters

• name (str) — Name of the profile.

Returns

• ProfileConfig — The removed profile.

Raises

• KSeFValidationError — If the profile is not defined.

TestCertificateProfileAuth

Import: from ksef2.profiles import TestCertificateProfileAuth

class TestCertificateProfileAuth(ProfileAuthConfig)

Authentication settings for the SDK-generated TEST certificate; type defaults to test_certificate.

Attributes

• type: ProfileAuthType — Authentication method; test_certificate.

TokenProfileAuth

Import: from ksef2.profiles import TokenProfileAuth

class TokenProfileAuth(ProfileAuthConfig)

Authentication settings for token authentication; type defaults to token.

Attributes

• type: ProfileAuthType — Authentication method; token.

XadesP12ProfileAuth

Import: from ksef2.profiles import XadesP12ProfileAuth

class XadesP12ProfileAuth(ProfileAuthConfig)

Authentication settings for XAdES with a PKCS#12/PFX archive; type defaults to xades_p12.

Attributes

• type: ProfileAuthType — Authentication method; xades_p12.

XadesPemProfileAuth

Import: from ksef2.profiles import XadesPemProfileAuth

class XadesPemProfileAuth(ProfileAuthConfig)

Authentication settings for XAdES with a PEM certificate and key; type defaults to xades_pem.

Attributes

• type: ProfileAuthType — Authentication method; xades_pem.

Enumerations

ProfileAuthType

Import: from ksef2.profiles import ProfileAuthType

class ProfileAuthType(StrEnum)

Authentication methods a profile can use.

Values

ProfileEnvironment

Import: from ksef2.profiles import ProfileEnvironment

class ProfileEnvironment(StrEnum)

KSeF environment names as written in profile files.

Values

Functions

default_profile_config_path

Import: from ksef2.profiles import default_profile_config_path

def default_profile_config_path(environ: Mapping[str, str] | None = None) -> Path

Resolve the default config file location.

Uses KSEF2_CONFIG when set, otherwise ksef2/config.toml under XDG_CONFIG_HOME (or ~/.config), falling back to the legacy ksef2-cli directory when only that exists.

Parameters

• environ (Mapping[str, str] | None) — Environment mapping to read; os.environ when None.

Returns

• Path — Path of the config file.

load_cli_profile

Import: from ksef2.profiles import load_cli_profile

def load_cli_profile(
    name: str | None = None,
    *,
    config_path: str | Path | None = None,
    environ: Mapping[str, str] | None = None,
) -> tuple[str, ProfileConfig]

Select and load a profile the way the CLI does.

The profile is chosen from name, then KSEF2_PROFILE, then the config's active_profile.

Parameters

• name (str | None) — Profile name to load; None to fall back to the environment variable and active profile.
• config_path (str | Path | None) — Path of the config file; the default location is used when None.
• environ (Mapping[str, str] | None) — Environment mapping to read; os.environ when None.

Returns

• tuple[str, ProfileConfig] — The selected profile's name and settings.

Raises

• KSeFValidationError — If no profile is selected, the profile is not defined, or the config file is invalid.

load_profile_config

Import: from ksef2.profiles import load_profile_config

def load_profile_config(path: str | Path | None = None) -> CliProfileConfig

Read and validate a profile config file.

Parameters

• path (str | Path | None) — Path of the config file; the default location is used when None.

Returns

• CliProfileConfig — The parsed config; empty when the file does not exist.

Raises

• KSeFValidationError — If the file is not valid TOML or does not match the profile schema.

render_profile_config

Import: from ksef2.profiles import render_profile_config

def render_profile_config(config: CliProfileConfig) -> str

Render a profile config as TOML text.

Parameters

• config (CliProfileConfig) — Config to render.

Returns

• str — The TOML document.

write_profile_config

Import: from ksef2.profiles import write_profile_config

def write_profile_config(path: str | Path, config: CliProfileConfig) -> None

Write a profile config file, creating parent directories and restricting permissions to the owner.

Parameters

• path (str | Path) — Path of the config file.
• config (CliProfileConfig) — Config to write.

Raises

• KSeFValidationError — If the file cannot be written.

Constants

CONFIG_ENV_VAR

Import: from ksef2.profiles import CONFIG_ENV_VAR

CONFIG_ENV_VAR = 'KSEF2_CONFIG'

Profile

Import: from ksef2.profiles import Profile

Profile = ProfileConfig

PROFILE_ENV_VAR

Import: from ksef2.profiles import PROFILE_ENV_VAR

PROFILE_ENV_VAR = 'KSEF2_PROFILE'