libdev 0.95__tar.gz → 0.96__tar.gz

{libdev-0.95 → libdev-0.96}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: libdev
-Version: 0.95
+Version: 0.96
 Summary: Set of standard functions for development
 Home-page: https://github.com/chilleco/lib
 Author: Alex Poloz

{libdev-0.95 → libdev-0.96}/libdev/__init__.py

@@ -2,6 +2,6 @@
 Initializing the Python package
 """
 
-__version__ = "0.95"
+__version__ = "0.96"
 
 __all__ = ("__version__",)

{libdev-0.95 → libdev-0.96}/libdev/cfg.py

@@ -1,5 +1,10 @@
-"""
-Functionality of getting configuration
+"""Centralized configuration loader for LibDev consumers.
+
+This module mirrors the behavior documented in `LIBDEV_DOCUMENTATION.md`:
+it first ingests a project level ``sets.json`` file, then overlays values
+from ``.env`` (via ``python-dotenv``) by translating dotted keys to
+``UPPER_SNAKE_CASE`` environment variables. Use the helpers below instead of
+calling ``os.getenv`` throughout the codebase so the hierarchy stays uniform.
 """
 
 import os
@@ -19,7 +24,15 @@ if os.path.isfile(".env"):
 
 
 def cfg(name, default=None):
-    """Get config value by key"""
+    """Return a config value stored in ``sets.json``/``.env``.
+
+    The lookup walks dotted paths inside the parsed JSON structure and, when a
+    key is missing, falls back to an environment variable where dots are
+    replaced with underscores and the string is upper-cased (``api.base`` →
+    ``API_BASE``). Environment values are JSON-decoded automatically so booleans
+    and numeric strings turn into native Python types. ``default`` is returned
+    when a key is absent in both sources.
+    """
 
     keys = name.split(".")
     data = sets
@@ -44,7 +57,13 @@ def cfg(name, default=None):
 
 
 def set_cfg(name, value):
-    """Set config value"""
+    """Mutate the in-memory ``sets`` dictionary for tests or overrides.
+
+    Writes scoped dotted keys back into the ``sets`` mapping without touching
+    disk. This mirrors the behavior in consumer repos that temporarily adjust
+    configuration for integration tests or AI agents. Changes live only for the
+    current process and should be reset between tests.
+    """
 
     array_name = name.split(".")
     dictionary = {}

{libdev-0.95 → libdev-0.96}/libdev/check.py

@@ -239,4 +239,5 @@ def get_url(data: str) -> str | None:
 
 
 def clear_text(data, extra=".,"):
+    """Strip all characters except alphanumerics, space, and ``extra`` chars."""
     return re.sub(rf"[^\w {extra}]", "", data).strip()

libdev-0.96/libdev/dev.py

@@ -0,0 +1,29 @@
+"""Development-environment helpers tied to LibDev guidelines.
+
+Currently exposes public IP validation logic that mirrors the rules documented
+in ``LIBDEV_DOCUMENTATION.md`` for analytics and logging pipelines. Extend this
+module instead of sprinkling regex checks throughout consumer projects.
+"""
+
+import re
+
+
+def check_public_ip(ip):
+    """Return ``ip`` if it is routable on the public internet.
+
+    Private (RFC1918), loopback, and carrier-grade NAT subnets are filtered
+    out, ensuring only analyzable public addresses pass downstream. ``None`` is
+    returned for empty inputs or addresses that match reserved ranges.
+    """
+
+    if not ip:
+        return None
+
+    return (
+        None
+        if re.match(
+            r"^(172\.(1[6-9]\.|2[0-9]\.|3[0-1]\.)|192\.168\.|10\.|127\.)",
+            ip,
+        )
+        else ip
+    )

libdev-0.96/libdev/doc.py

@@ -0,0 +1,29 @@
+"""Utility helpers for dealing with document/JSON serialization.
+
+These functions are referenced by the integration guide to make sure assets
+and structured logs look the same across repositories (e.g., ``log.json`` uses
+``to_json`` under the hood).
+"""
+
+import base64
+import json
+
+
+def to_base64(image, mime="image/jpg"):
+    """Return a ``data:`` URL for the given file-like ``image``.
+
+    Reads the stream, base64-encodes the bytes, and prefixes it with the MIME
+    Type so downstream clients (frontends, bots) can embed the payload directly
+    without touching disk.
+    """
+    data = base64.b64encode(image.read())
+    return f"data:{mime};base64,{data.decode('utf-8')}"
+
+
+def to_json(data):
+    """Serialize ``data`` to a UTF-8 friendly JSON string.
+
+    Uses tab indentation and ``ensure_ascii=False`` to preserve Cyrillic or
+    emoji content mentioned in ``LIBDEV_DOCUMENTATION.md``.
+    """
+    return json.dumps(data, indent="\t", ensure_ascii=False)

{libdev-0.95 → libdev-0.96}/libdev/num.py

@@ -1,5 +1,8 @@
-"""
-Numbers functionality
+"""Numeric normalization and presentation helpers used across LibDev.
+
+Implements the opinionated formatting rules discussed in the integration
+guide: deterministic rounding, removal of floating-point artifacts, thousands
+separators, and zero-compression for compact analytical displays.
 """
 
 import re
@@ -22,7 +25,7 @@ def is_float(value: str) -> bool:
 
 
 def to_num(value) -> bool:
-    """Convert value to int or float"""
+    """Convert an incoming scalar to ``int``/``float`` while preserving intent."""
 
     if value is None:
         return None
@@ -80,7 +83,11 @@ def get_whole(value):
 
 
 def simplify_value(value, decimals=4):
-    """Get the significant part of a number"""
+    """Return the significant digits of ``value`` capped by ``decimals``.
+
+    Used by analytics pipelines to produce short strings that still encode the
+    important portion of very large or tiny numbers.
+    """
 
     if value is None:
         return None
@@ -126,7 +133,13 @@ def pretty(
     zeros=4,
     compress=None,
 ):
-    """Decorate the number beautifully"""
+    """Format ``value`` according to LibDev UI/metrics rules.
+
+    Supports optional rounding to a target precision, manual sign prefixing,
+    swapping the thousands separator symbol, and compressing leading/trailing
+    zeros (see ``compress_zeros``). This helper is the canonical way to build
+    user-facing number strings.
+    """
 
     if value is None:
         return None
@@ -282,6 +295,8 @@ def to_step(value, step=1, side=False):
 
 
 def to_plain(value) -> str:
+    """Convert ``value`` to a normalized decimal string without notation."""
+
     if value is None:
         return None
     try:
@@ -311,11 +326,17 @@ def _round_to_decimals(x, decimals):
 
 
 def compress_zeros(x, zeros=2, round=None) -> str:
-    """
-    0.000012 -> '0.0₄12'
-    1.000045 -> '1.0₄45'
-    round: number of digits after the zero block (rounds).
-    zeros: minimum count of consecutive zeros to compress (default: 2).
+    """Compress zero runs using the subscript notation referenced in the docs.
+
+    Examples::
+
+        0.000012 -> "0.0₄12"
+        1.000045 -> "1.0₄45"
+
+    ``round`` controls how many digits remain after the compressed block, while
+    ``zeros`` sets the minimum run length required before a compression occurs.
+    Returns a string that can be passed to ``pretty`` or directly displayed in
+    dashboards.
     """
 
     if x is None:

{libdev-0.95 → libdev-0.96}/libdev/req.py

@@ -1,5 +1,9 @@
-"""
-Provides an asynchronous function to fetch data from a URL using aiohttp
+"""Async HTTP gateway used across LibDev powered projects.
+
+Centralizes ``aiohttp`` usage so upstream services benefit from the same request
+construction (JSON vs form payloads, multipart file uploads) and response
+parsing rules described in ``LIBDEV_DOCUMENTATION.md``. Always ``await`` the
+helpers in this module to stay inside the async boundary.
 """
 
 import aiohttp
@@ -14,24 +18,15 @@ async def fetch(
     headers=None,
     timeout=None,
 ):
-    """
-    Fetch data from a URL using aiohttp.
-
-    Args:
-        url (str): The URL to fetch data from.
-        payload (dict, optional): The payload to send with the request.
-            Defaults to None.
-        type_req (str, optional): The type of request (e.g., 'post', 'put',
-            'delete', etc.). Defaults to 'post'.
-        type_data (str, optional): The type of data (e.g., 'json', 'data').
-            Defaults to 'json'.
-        headers (dict, optional): The headers to include with the request.
-            Defaults to None.
-        timeout (float, optional): The timeout for the request in seconds.
-            Defaults to None.
+    """Perform an HTTP request and normalize the response payload.
 
-    Returns:
-        tuple: A tuple containing the status code and the response data.
+    Parameters mirror the rules from the integration guide: ``files`` may be a
+    mapping of field name to bytes/file-like objects (forcing multipart form
+    uploads), ``type_data`` controls whether the ``payload`` is supplied via the
+    ``json`` or ``data`` keyword, and ``type_req`` is the lowercase HTTP verb. A
+    status code integer and the decoded response body (JSON dict, plain text, or
+    raw bytes) are returned. Callers are expected to provide their own retries
+    or circuit breaking logic.
     """
     if payload is None:
         payload = {}

{libdev-0.95 → libdev-0.96}/libdev/time.py

@@ -1,5 +1,8 @@
-"""
-Time functionality
+"""Datetime parsing/formatting helpers aligned with LibDev localization rules.
+
+The functions below implement the Russian month parsing, timezone handling, and
+delta formatting conventions cited in ``LIBDEV_DOCUMENTATION.md`` so every
+project surfaces dates the same way.
 """
 
 # TODO: Учитывать летнее / зимнее время в прошлых датах, которого теперь нет
@@ -51,13 +54,15 @@ def to_tz(hours):
     return datetime.timezone(datetime.timedelta(hours=hours))
 
 
-def get_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=0):
+def get_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=None):
     """Get time from timestamp"""
 
     if data is None:
         data = time.time()
     if isinstance(data, str):
         return data
+    if tz is None:
+        tz = 0
 
     # TODO: smart TZ
 
@@ -67,18 +72,20 @@ def get_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=0):
     return time.strftime(template, time.gmtime(data + tz * 3600))
 
 
-def get_date(data=None, template="%d.%m.%Y", tz=0):
+def get_date(data=None, template="%d.%m.%Y", tz=None):
     """Get date from timestamp"""
     return get_time(data, template, tz)
 
 
-def decode_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=0):
+def decode_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=None):
     """Get timestamp from time"""
 
     if not data:
         return None
     if isinstance(data, int):
         return data
+    if tz is None:
+        tz = 0
 
     try:
         data = datetime.datetime.strptime(data, template)
@@ -90,17 +97,20 @@ def decode_time(data=None, template="%d.%m.%Y %H:%M:%S", tz=0):
     return int(data.timestamp())
 
 
-def decode_date(data=None, template="%d.%m.%Y", tz=0):
+def decode_date(data=None, template="%d.%m.%Y", tz=None):
     """Get timestamp from date"""
     return decode_time(data, template, tz)
 
 
 # pylint: disable=too-many-branches,too-many-statements
-def parse_time(data: str, tz=0):
+def parse_time(data: str, tz=None):
     """Parse time"""
 
     # TODO: 16 year -> 2016 year
 
+    if tz is None:
+        tz = 0
+
     data = data.lower()
 
     # Cut special characters
@@ -264,7 +274,7 @@ def format_delta(sec, short=False, locale="en"):
     return delta
 
 
-def get_midnight(timestamp=None, tz=0):
+def get_midnight(timestamp=None, tz=None):
     """
     Get the start of the day (midnight) for a given timestamp in a specified timezone.
 
@@ -275,14 +285,19 @@ def get_midnight(timestamp=None, tz=0):
     Returns:
         float: The timestamp for the start of the day (midnight) in the specified timezone.
     """
+
     if timestamp is None:
         timestamp = time.time()
+    if tz is None:
+        tz = 0
+
     dt_local = datetime.datetime.fromtimestamp(timestamp, tz=to_tz(tz))
     start_day = dt_local.replace(hour=0, minute=0, second=0, microsecond=0)
+
     return int(start_day.timestamp())
 
 
-def get_month_start(timestamp=None, tz=0):
+def get_month_start(timestamp=None, tz=None):
     """
     Get the start of the month (midnight on the first day of the month) for a given timestamp in a specified timezone.
 
@@ -293,14 +308,25 @@ def get_month_start(timestamp=None, tz=0):
     Returns:
         float: The timestamp for the start of the month in the specified timezone.
     """
+
     if timestamp is None:
         timestamp = time.time()
+    if tz is None:
+        tz = 0
+
     dt_local = datetime.datetime.fromtimestamp(timestamp, tz=to_tz(tz))
     start_month = dt_local.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+
     return int(start_month.timestamp())
 
 
-def get_week_start(timestamp=None, tz=0):
+def get_previous_month(timestamp=None, tz=None):
+    current_period = get_month_start(timestamp, tz)
+    one_month_ago = get_month_start(current_period - 1, tz)
+    return one_month_ago
+
+
+def get_week_start(timestamp=None, tz=None):
     """
     Get the start of the week (midnight on Monday) for a given timestamp in a specified timezone.
 
@@ -311,17 +337,23 @@ def get_week_start(timestamp=None, tz=0):
     Returns:
         float: The timestamp for the start of the week (Monday at midnight) in the specified timezone.
     """
+
     if timestamp is None:
         timestamp = time.time()
+    if tz is None:
+        tz = 0
+
     dt_local = datetime.datetime.fromtimestamp(timestamp, tz=to_tz(tz))
     # Calculate days to subtract to get to Monday (weekday() returns 0 for Monday, 6 for Sunday)
     days_since_monday = dt_local.weekday()
+
     start_week = dt_local - datetime.timedelta(days=days_since_monday)
     start_week = start_week.replace(hour=0, minute=0, second=0, microsecond=0)
+
     return int(start_week.timestamp())
 
 
-def get_next_day(timestamp=None, tz=0):
+def get_next_day(timestamp=None, tz=None):
     """
     Get the start of the next day (midnight) for a given timestamp in a specified timezone.
 
@@ -332,17 +364,22 @@ def get_next_day(timestamp=None, tz=0):
     Returns:
         float: The timestamp for the start of the next day (midnight) in the specified timezone.
     """
+
     if timestamp is None:
         timestamp = time.time()
+    if tz is None:
+        tz = 0
+
     dt_local = datetime.datetime.fromtimestamp(timestamp, tz=to_tz(tz))
     next_day = (dt_local + datetime.timedelta(days=1)).replace(
         hour=0, minute=0, second=0, microsecond=0
     )
+
     return int(next_day.timestamp())
 
 
 # TODO: get previous month (params=-1 +1)
-def get_next_month(timestamp=None, tz=0):
+def get_next_month(timestamp=None, tz=None):
     """
     Get the start of the next month (midnight on the first day of the next month) for a given timestamp in a specified timezone.
 
@@ -356,6 +393,8 @@ def get_next_month(timestamp=None, tz=0):
 
     if timestamp is None:
         timestamp = time.time()
+    if tz is None:
+        tz = 0
 
     dt_local = datetime.datetime.fromtimestamp(timestamp, tz=to_tz(tz))
 

{libdev-0.95 → libdev-0.96}/libdev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: libdev
-Version: 0.95
+Version: 0.96
 Summary: Set of standard functions for development
 Home-page: https://github.com/chilleco/lib
 Author: Alex Poloz

{libdev-0.95 → libdev-0.96}/tests/test_num.py

@@ -157,6 +157,7 @@ def test_pretty():
     assert pretty(123.456, 1) == "123"
     assert pretty(123.456, 1, True) == "+123"
     assert pretty(12345.6, 3, True) == "+12’346"
+    assert pretty(1046012.4859999998, 0) == "1’046’012"
     assert pretty(-0.000000235235, zeros=None, compress=None) == "-0.000000235235"
     assert pretty(-0.000000235235, zeros=4, compress=2) == "-0.0₆24"
 

{libdev-0.95 → libdev-0.96}/tests/test_time.py

@@ -13,6 +13,7 @@ from libdev.time import (
     format_delta,
     get_midnight,
     get_month_start,
+    get_previous_month,
     get_next_day,
     get_next_month,
     get_delta_days,
@@ -121,6 +122,12 @@ def test_get_month_start():
     assert get_month_start(1704060061, tz=3) == 1704056400
 
 
+def test_get_previous_month():
+    assert get_previous_month() == 1759276800
+    assert get_previous_month(tz=3) == 1759266000
+    assert get_previous_month(1760648400, 1) == 1756681200
+
+
 def test_get_next_day():
     assert get_next_day(1704060061) == 1704067200
     assert get_next_day(1704060061, tz=3) == 1704142800

libdev-0.95/libdev/dev.py

@@ -1,21 +0,0 @@
-"""
-Development tools
-"""
-
-import re
-
-
-def check_public_ip(ip):
-    """Check if the IP address is public"""
-
-    if not ip:
-        return None
-
-    return (
-        None
-        if re.match(
-            r"^(172\.(1[6-9]\.|2[0-9]\.|3[0-1]\.)|192\.168\.|10\.|127\.)",
-            ip,
-        )
-        else ip
-    )

libdev-0.95/libdev/doc.py

@@ -1,17 +0,0 @@
-"""
-Documents processing functionality
-"""
-
-import base64
-import json
-
-
-def to_base64(image, mime="image/jpg"):
-    """Convert image to base64"""
-    data = base64.b64encode(image.read())
-    return f"data:{mime};base64,{data.decode('utf-8')}"
-
-
-def to_json(data):
-    """Convert object to json"""
-    return json.dumps(data, indent="\t", ensure_ascii=False)