Ebloky Implementation Reference

Introduction 

This section documents the internal implementation of the Ebloky module. The API reference is auto-generated from in-source docstrings found in src/ebloky.py.

Helper Functions 

ebloky._logger_trace(self, message, *args, **kws) → None

Log a message at TRACE level.

Args:: self (logging.Logger): Logger instance. message (str): Message to log. args: Format arguments (tuple). kws: Additional keyword arguments (dict).

ebloky.trace(msg, *args, **kws) → None

Log a message at TRACE level (module-level convenience function).

Args:: msg (str): Message to log. args: Format arguments (tuple). kws: Additional keyword arguments (dict).

Logger 

class ebloky.Logger(name, level=0, verbose=0)

Bases: Logger

Custom logger with support for TRACE level and dual output streams.

Logs to both a file (ebloky.log) and console with configurable verbosity.

RequestManager 

class ebloky.RequestManager(cap: int = 999)

Bases: object

Manage construction and execution of HTTP requests to e-bloc AJAX endpoints.

The RequestManager centralizes headers, cookie construction and a small service matrix mapping friendly service keys to URL, payload defaults and output types.

executeRequest(req: dict) → tuple

Execute a forged request descriptor and return status and parsed data.

Args:

req (dict): Request descriptor produced by forgeRequest.

Returns:

tuple: (status_code, data) where data is the parsed JSON or: raw text/bytes depending on the declared output.

forgeCookie() → str

Build the cookie header string from the internal cookie template.

Returns:: str: Semicolon-delimited cookie string (e.g. “PHPSESSID=…;username=…”).

forgeRequest(service: str, sessiondata: dict, custom: dict = {}) → dict

Return a request descriptor for a given service key.

Args:

service (str): One of the known service keys (e.g. “AjaxGetHomeAp”). sessiondata (dict): Session dictionary used to populate cookies and headers. custom (dict): Service-specific overrides (payload params, months, ids).

Returns:

dict: A request descriptor containing keys like method, url, header,: payload, params and output.

getRemainingRequest() → int

Return the number of remaining requests allowed for this manager.

Returns:

int: Remaining request allowance (decrements on each successful: call to executeRequest).

loadCookie(cookie: dict) → str

Merge provided session values into the cookie template and return a Cookie header string.

Args:: cookie (dict): Session values (may include PHPSESSID, ASID, APID, username).
Returns:: str: A semicolon-separated cookie header value.

Ebloky Client 

class ebloky.Ebloky(requestcap: int = 999, verbose: int = 0)

Bases: object

Public wrapper exposing e-bloc convenience methods.

Ebloky provides higher-level methods that use RequestManager to interact with e-bloc’s AJAX endpoints. Methods return parsed data and are intentionally small to make testing and mocking straightforward.

canSendIndex(qdate: date | None = None) → bool

Return True if index submissions are allowed for qdate.

If qdate is None the current date is used.

Args:: qdate (date|None): Optional date to test.
Returns:: bool: True if within the submission window.

documentsAvailableFor(year: int, month: int, pattern: Pattern | None = None) → bool

Return True if documents exist for the given year/month.

When pattern is omitted the method simply checks the month list returned by AjaxGetAvizierLuni (existing behaviour). If a compiled regular expression is provided, the method will fetch the documents for the specified month and return True only if at least one document title matches the pattern. This enables callers to quickly verify the presence of particular kinds of files without downloading them.

Args:

year (int): Year. month (int): Month. pattern (Pattern | None): Optional compiled re pattern to test

document titlu fields. If provided the month is considered available only when a matching document exists.

Returns:

bool: True if documents are available (and if pattern given,: at least one document matches it).

getAvaiableAp(asid: int | None = None) → dict

Return a mapping of available apartment IDs to their display titles.

If asid is provided the internal session ASID is updated so subsequent calls use the supplied association id.

Args:: asid (int|None): Optional association id to scope the query.
Returns:: dict: Mapping of id_ap -> titlu for available apartments.

getDiscutions(cap: int = 999) → dict

Fetch subjects and their replies.

This method aggregates __getSubjects and __getChatReplays and returns a mapping where each subject includes a replays key with replies.

Args:: cap (int): Maximum subjects/replies to fetch.
Returns:: dict: Aggregated subjects with replies.

getDocsInRange(pattern: Pattern, start: date, end: date, out_dir: Path) → tuple[bool, int, list]

Download documents matching a filename regex pattern within a date range.

This method retrieves all documents between the specified start and end dates (inclusive), filters them based on the provided compiled regex pattern, and downloads matching documents to the specified output directory.

The function uses the document title field (‘titlu’) for pattern matching and automatically constructs the filename using the document ID and extension.

Args:

pattern (Pattern): Compiled regex pattern object (use re.compile()) to match: document titles. For example: re.compile(r’.*invoice.*’) or re.compile(r’Lista de plată.*’).

start (date): Start date (inclusive). Must be a datetime.date object. end (date): End date (inclusive). Must be a datetime.date object. out_dir (Path): Directory where downloaded documents will be saved.

Created automatically if it doesn’t exist.

Returns:

tuple[bool, int, list]:: bool: True if at least one document was downloaded. int: Number of downloaded documents. list: List of file paths written to out_dir.

Raises:

OSError: If the output directory cannot be created.

Example:

>>> from pathlib import Path
>>> from datetime import date
>>> import re
>>> eb = Ebloky()
>>> eb.loadsession(Path("./session.json"))
>>> pattern = re.compile(r".*invoice.*")
>>> success, _ = eb.getDocsInRange(
...     pattern=pattern,
...     start=date(2025, 9, 1),
...     end=date(2025, 10, 31),
...     out_dir=Path("./documents")
... )
>>> if success:
...     print("Documents downloaded successfully")

getDocumentIdsInRange(start: date, end: date, pattern: Pattern | None = None) → list[int]

Return document IDs within a date range, optionally matching a regex.

This helper mirrors getDocsInRange but does not download files. It scans all available documents whose month falls between start and end (inclusive) and returns a list of their numeric IDs. The latter behavior is convenient when you only expect a specific document and want to avoid unpacking a singleton list.

Args:

start (date): Start date (inclusive). end (date): End date (inclusive). pattern (Pattern | None): Optional compiled regex. Only documents with

titles matching the pattern will be considered.

Returns:

list[int]: If pattern is None or multiple documents match the: criteria, a list of IDs is returned. If pattern is provided and exactly one document matches, that document’s ID is returned directly. An empty list is returned when no documents satisfy the criteria.

Example:

>>> from datetime import date
>>> import re
>>> eb = Ebloky()
>>> eb.loadsession(Path("./session.json"))
>>> ids = eb.getDocumentIdsInRange(
...     start=date(2025, 10, 1),
...     end=date(2025, 10, 31),
... )
>>> print(ids)
[39197069, 39197070]

# filter by title content >>> ids = eb.getDocumentIdsInRange( … start=date(2025, 10, 1), … end=date(2025, 10, 31), … pattern=re.compile(r”invoice”), … )

getLiabilities(year: int, month: int) → list

Return liabilities (debts) for a specific month.

Args:: year (int): Year. month (int): Month.
Returns:: list: Matching liabilities for the given month.

getPaymentRecipe(year: int, month: int) → list

Return payment recipes for the specified month.

Args:: year (int): Year. month (int): Month.
Returns:: list: Matching payment recipes.

getRemainingRequests() → int

Return remaining request allowance from the internal manager.

Returns:

int: Number of requests that can still be made before the: manager blocks further requests.

loadsession(path: Path) → None | bool

Load a session from a JSON file.

Args:: path (Path): Path to a JSON file containing a session dict.
Returns:: bool: True on success, or None if the file does not exist.

loadssession(cookie: dict) → None | bool

Load an active session from a dictionary.

The session dict should include keys such as PHPSESSID, ASID, APID and optionally username. This method updates the internal RequestManager cookie template and stores the session for subsequent requests.

Args:: cookie (dict): Session values.
Returns:: bool: True on success.

printApNames(asid: int | None = None) → None

Print the human-readable names of available apartments to stdout.

If asid is provided the internal session ASID is updated before fetching apartment names.

Args:: asid (int|None): Optional association id to scope the query.
Returns:: None

setApID(apid: int) → bool

Set the session APID value and update the internal cookie template.

Args:: apid (int): Apartment id to set in the session.
Returns:: bool: Always returns True after setting the value.

setAsID(asid: int) → bool

Set the session ASID value and update the internal cookie template.

Args:: asid (int): Association id to set in the session.
Returns:: bool: Always returns True after setting the value.

Ebloky Implementation Reference

Introduction

Helper Functions

Logger

RequestManager

Ebloky Client

Introduction 

Helper Functions 

Logger 

RequestManager 

Ebloky Client 