ebloky

Lightweight Python client for interacting with the e-bloc platform (e-bloc.ro).

Table of Contents

• Overview: short project summary and purpose
• Quick Start: minimal usage example for Ebloky
• Architecture: high-level components and responsibilities
• Implementation Details: important internals and design choices
• Usage & Examples: example code and common calls
• Best Practices: recommended patterns for safe usage
• License: MIT license and liability

Overview

ebloky is a small library that wraps the e-bloc AJAX endpoints and provides convenient methods to load a session and fetch common resources such as discussion subjects, replies, monthly documents and apartment/home data.

The library focuses on a pragmatic mapping from endpoint names to simple Python calls while providing a RequestManager that centralizes request construction and execution.

Quick Start

Install the package (from source or your packaging flow), then use Ebloky:

from pathlib import Path
from ebloky import Ebloky

e = Ebloky(verbose=1)

# either load a session dictionary you already have
session = {
    "PHPSESSID": "YOUR_SESSION_ID",
    "ASID": 123,
    "APID": 456,
    "username": "you@example.com",
}
e.loadssession(session)

# helper methods: list available apartments and set ids used by other calls
available = e.getAvaiableAp()
print("Available apartments:", available)
# set association or apartment id for subsequent calls
e.setAsID(123)
e.setApID(456)

# Example: download documents that match a filename pattern in a date range
from datetime import date
import re
pattern = re.compile(r".*invoice.*")
success, count, paths = e.getDocsInRange(
  pattern=pattern,
  start=date(2025, 9, 1),
  end=date(2025, 10, 31),
  out_dir=Path("./documents"),
)
if success:
  print(f"Downloaded {count} documents to: {paths}")

Architecture

• Ebloky (wrapper): Public API used by callers. Holds a RequestManager and a session dict. Exposes convenience methods like getDiscutions, getDocumentsForMonth, and downloadDocument.
• RequestManager: Responsible for forging requests (headers, cookies, endpoints, payloads) and executing HTTP calls via requests.
• Logging: a small custom Logger attaches a TRACE level and writes both to ebloky.log (file) and stdout with configurable verbosity.
• Service matrix: RequestManager.forgeRequest maps simple service keys (e.g. AjaxGetHomeAp, DownloadAvizierDoc) to URLs, payload defaults and output types. This keeps per-endpoint details centralized.

Implementation Details

• Cookie/session model: RequestManager keeps a cookie template with keys such as PHPSESSID, ASID, APID, username. Use Ebloky.loadssession() to populate the live session values the library will use to build Cookie headers.
• Request forging: forgeRequest(service, sessiondata, custom) returns a request descriptor with method, url, header, payload, params and an output type. executeRequest() runs the HTTP call and attempts to decode JSON; if decoding fails it falls back to text or bytes depending on the declared output.
• Return shapes: executeRequest() returns a (status_code, data) tuple; the Ebloky wrapper methods usually discard status and return parsed data.
• File downloads: downloadDocument(docid, path) will write the raw bytes returned from the DownloadAvizierDoc endpoint to the given Path.

Usage & Examples

• Load a session from file:

from pathlib import Path
from ebloky import Ebloky

e = Ebloky()
e.loadsession(Path("./session.json"))

• List discussion subjects and replies:
• List discussion subjects and replies:

# `getDiscutions` aggregates subjects and their replies into a mapping
disc = e.getDiscutions(cap=100)
for subj_id, subj in disc.items():
  print(subj.get("titlu"))
  for r in subj.get("replays", []):
    print(" -", r.get("titlu"))

• Check if documents exist for a month and download one:
• Check if documents exist for a month and download matching files:
• Retrieve document IDs without downloading:

# the availability helper also accepts an optional compiled regex pattern
# which will perform a quick title search within the month instead of only
# checking for the month’s existence.
if e.documentsAvailableFor(2025, 10):
  # Prefer the range/pattern downloader for batch operations; low-level
  # single-file download helpers are intentionally private.
  from datetime import date
  import re

  pattern = re.compile(r".*invoice.*")
  e.getDocsInRange(
    pattern=pattern,
    start=date(2025, 9, 1),
    end=date(2025, 10, 31),
    out_dir=Path("./invoices"),
  )

# example use of the new helper to just get IDs:
# (if a regex is provided and exactly one document matches, the method
# returns the integer id directly instead of a one-element list)
ids = e.getDocumentIdsInRange(start=date(2025, 10, 1), end=date(2025, 10, 31))
print("IDs in range:", ids)

Best Practices

• Secure sessions: store PHPSESSID and other sensitive session data outside source control and load them at runtime (e.g. environment, secrets manager, or an encrypted local store).
• Error handling: many methods trust endpoint responses. Wrap calls in try/except and validate data shapes before use.
• Rate limiting & retry: RequestManager reduces allowreq on each call; add retry/backoff logic and respect the remote service's usage policies. The library also supports a requestcap feature: pass requestcap to Ebloky() to limit how many outbound requests the internal manager will perform during a run. Query the remaining allowance with e.getRemainingRequests().
• Tests & mocking: when writing tests, mock requests.post and requests.get and assert the right payloads and headers are sent.

Development notes

• Logging: the module configures a custom TRACE level for very verbose diagnostics. Configure the module-level logger (see the Logger class) or instantiate Logger directly to enable TRACE output. The verbose argument on Ebloky() is currently reserved and not applied by the instance.
• Endpoint matrix: to add or adjust endpoint behavior, update RequestManager.forgeRequest() where service keys are mapped to url, payload, params and output types.

License

• This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer / No Liability

• This software is provided "as is", without warranty of any kind. The authors and contributors are not liable for any damages arising from use of this software.

Fair Use & Educational Notice

• The API documentation and examples in this repository have been compiled purely for educational purposes and to demonstrate how one may interact with the e-bloc platform. No attempt has been made to bypass protections, harm the service, or infringe on any rights. All information is derived from the public-facing interface and is presented under the principles of fair use. The author disclaims any intent or responsibility for misuse and seeks to be fully exonerated from any legal or ethical claims related to these materials.