firebird-base 2.0.3__tar.gz → 2.0.4__tar.gz

{firebird_base-2.0.3 → firebird_base-2.0.4}/.gitignore

@@ -133,12 +133,9 @@ dmypy.json
 *.wpr
 *.wpu
 
-# Sphinx build
-docs/_build
+# Doc build
+docs/site
 docs/firebird-base.docset/
 
 # Other local files and directories
 local/
-
-# Great Docs build directory (ephemeral, do not commit)
-great-docs/

firebird_base-2.0.4/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: firebird-base
+Version: 2.0.4
+Summary: Firebird base modules for Python
+Project-URL: Home, https://github.com/FirebirdSQL/python3-base
+Project-URL: Documentation, https://firebird-base.rtfd.io
+Project-URL: Issues, https://github.com/FirebirdSQL/python3-base/issues
+Project-URL: Funding, https://github.com/sponsors/pcisar
+Project-URL: Source, https://github.com/FirebirdSQL/python3-base
+Author-email: Pavel Cisar <pcisar@users.sourceforge.net>
+License: 
+        MIT License
+        ===========
+        
+        Copyright (c) 2019 The Firebird Project (www.firebirdsql.org)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: Collections,Configuration,Firebird,Hooks,Logging,Protobuf,Signals,Trace
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development
+Requires-Python: <4,>=3.11
+Requires-Dist: protobuf~=5.29
+Description-Content-Type: text/markdown
+
+# firebird-base
+
+## Firebird base modules for Python
+
+[![PyPI - Version](https://img.shields.io/pypi/v/firebird-base.svg)](https://pypi.org/project/firebird-base)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/firebird-base.svg)](https://pypi.org/project/firebird-base)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/firebird-base)](https://pypi.org/project/firebird-base)
+[![Libraries.io SourceRank](https://img.shields.io/librariesio/sourcerank/pypi/firebird-base)](https://libraries.io/pypi/firebird-base)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/FirebirdSQL/python3-base)
+
+`firebird-base` provides reusable Python modules used by the [Firebird Project](https://github.com/FirebirdSQL)
+and other applications. The modules can be used independently of the Firebird database.
+
+## Installation
+
+Requires Python `>=3.11,<4`.
+
+```console
+pip install firebird-base
+```
+
+Import the submodules you need, for example `import firebird.base.config`.
+
+## Documentation
+
+For module guides and API details, see the [firebird-base documentation](https://firebird-base.readthedocs.io/).
+
+## Agent skill
+
+The [firebird-base skill](skills/firebird-base/SKILL.md) provides guidance for using individual
+modules. Download `firebird-base-<version>-skill.zip` from
+[GitHub releases](https://github.com/FirebirdSQL/python3-base/releases) and extract its
+`firebird-base/` directory into the skill directory used by your coding agent. You can also
+copy or link the `skills/firebird-base` directory from this repository:
+
+| Agent | User skill directory |
+| --- | --- |
+| [Codex](https://learn.chatgpt.com/docs/build-skills) | `~/.codex/skills/` |
+| [Claude Code](https://code.claude.com/docs/en/skills) | `~/.claude/skills/` |
+| [Gemini CLI](https://geminicli.com/docs/cli/using-agent-skills/) | `~/.agents/skills/` (also supports `~/.gemini/skills/`) |
+
+## Development
+
+For the package map, dependencies, build and test workflow, and module maintenance notes,
+see [development/README.md](development/README.md) and the other files in [`development/`](development/).
+
+## License
+
+`firebird-base` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

firebird_base-2.0.4/README.md

@@ -0,0 +1,50 @@
+# firebird-base
+
+## Firebird base modules for Python
+
+[![PyPI - Version](https://img.shields.io/pypi/v/firebird-base.svg)](https://pypi.org/project/firebird-base)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/firebird-base.svg)](https://pypi.org/project/firebird-base)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/firebird-base)](https://pypi.org/project/firebird-base)
+[![Libraries.io SourceRank](https://img.shields.io/librariesio/sourcerank/pypi/firebird-base)](https://libraries.io/pypi/firebird-base)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/FirebirdSQL/python3-base)
+
+`firebird-base` provides reusable Python modules used by the [Firebird Project](https://github.com/FirebirdSQL)
+and other applications. The modules can be used independently of the Firebird database.
+
+## Installation
+
+Requires Python `>=3.11,<4`.
+
+```console
+pip install firebird-base
+```
+
+Import the submodules you need, for example `import firebird.base.config`.
+
+## Documentation
+
+For module guides and API details, see the [firebird-base documentation](https://firebird-base.readthedocs.io/).
+
+## Agent skill
+
+The [firebird-base skill](skills/firebird-base/SKILL.md) provides guidance for using individual
+modules. Download `firebird-base-<version>-skill.zip` from
+[GitHub releases](https://github.com/FirebirdSQL/python3-base/releases) and extract its
+`firebird-base/` directory into the skill directory used by your coding agent. You can also
+copy or link the `skills/firebird-base` directory from this repository:
+
+| Agent | User skill directory |
+| --- | --- |
+| [Codex](https://learn.chatgpt.com/docs/build-skills) | `~/.codex/skills/` |
+| [Claude Code](https://code.claude.com/docs/en/skills) | `~/.claude/skills/` |
+| [Gemini CLI](https://geminicli.com/docs/cli/using-agent-skills/) | `~/.agents/skills/` (also supports `~/.gemini/skills/`) |
+
+## Development
+
+For the package map, dependencies, build and test workflow, and module maintenance notes,
+see [development/README.md](development/README.md) and the other files in [`development/`](development/).
+
+## License
+
+`firebird-base` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

{firebird_base-2.0.3 → firebird_base-2.0.4}/pyproject.toml

@@ -22,6 +22,8 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Operating System :: POSIX :: Linux",
     "Operating System :: Microsoft :: Windows",
     "Operating System :: MacOS",
@@ -54,16 +56,10 @@ packages = ["src/firebird"]
 dependencies = [
 ]
 
-[tool.hatch.envs.gdocs]
-dependencies = [
-  "great-docs",
-]
-
-[tool.hatch.envs.gdocs.scripts]
-init = "great-docs init"
-scan = "great-docs scan"
-build = "great-docs build"
-preview = "great-docs preview"
+[tool.hatch.envs.default.scripts]
+build-config-proto = "protoc -I../protobuf --python_out=src --pyi_out=src firebird/base/config.proto"
+build-test-proto = "protoc -Itests --python_out=./tests --pyi_out=./tests base_test.proto"
+build-skill = "python scripts/build_skill.py"
 
 [tool.hatch.envs.hatch-test]
 extra-args = ["-vv"]
@@ -73,22 +69,21 @@ dependencies = [
 ]
 
 [[tool.hatch.envs.hatch-test.matrix]]
-python = ["3.11", "3.12", "3.13", "3.14"]
+python = ["3.11", "3.12", "3.13", "3.14", "3.15"]
 
 [tool.hatch.envs.doc]
 detached = false
-platforms = ["linux"]
 dependencies = [
-  "Sphinx==7.2.6",
-  "sphinx-bootstrap-theme>=0.8.1",
-  "sphinx-autodoc-typehints>=1.24.0",
+  "zensical",
+  "mkdocstrings-python",
   "doc2dash>=3.0.0"
 ]
 [tool.hatch.envs.doc.scripts]
-build = "cd docs ; make html"
+build = "cd docs && zensical build {args}"
+serve = "cd docs && zensical serve {args}"
 docset = [
-  "cd docs ; doc2dash -u https://firebird-base.readthedocs.io/en/latest/ -f -i ./_static/fb-favicon.png -n firebird-base ./_build/html/",
-  "cd docs; VERSION=`hatch version` ; tar --exclude='.DS_Store' -cvzf ../dist/firebird-base-$VERSION-docset.tgz firebird-base.docset",
+  "cd docs ; doc2dash -u https://firebird-base.readthedocs.io/en/latest/ -f -i ./site/assets/fb-favicon.png -n firebird-base ./site/",
+  "cd docs; VERSION=$(python -c 'from firebird.base.__about__ import __version__; print(__version__)') && tar --exclude='.DS_Store' -cvzf ../dist/firebird-base-$VERSION-docset.tgz firebird-base.docset",
 ]
 
 [tool.ruff]

{firebird_base-2.0.3 → firebird_base-2.0.4}/src/firebird/base/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2020-present The Firebird Projects <www.firebirdsql.org>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "2.0.3"
+__version__ = "2.0.4"

{firebird_base-2.0.3 → firebird_base-2.0.4}/src/firebird/base/buffer.py

@@ -34,9 +34,7 @@
 #                 ______________________________________
 
 
-"""Firebird Base - Memory buffer manager
-
-This module provides a `MemoryBuffer` class for managing raw memory buffers,
+"""This module provides a `MemoryBuffer` class for managing raw memory buffers,
 offering a convenient and consistent API for reading and writing various data types
 (integers of different sizes, strings with different termination/prefixing styles, raw bytes).
 It's particularly useful for tasks involving binary data serialization/deserialization,
@@ -44,12 +42,13 @@ such as implementing network protocols or handling custom file formats.
 
 The underlying memory storage can be customized via a `BufferFactory`. Two factories
 are provided:
+
 - `BytesBufferFactory`: Uses Python's built-in `bytearray`.
 - `CTypesBufferFactory`: Uses `ctypes.create_string_buffer` for potentially different
   memory characteristics or C-level interoperability.
 
-Example::
-
+Example:
+    ```python
     from firebird.base.buffer import MemoryBuffer, ByteOrder
 
     # Create a buffer (default uses bytearray)
@@ -73,10 +72,9 @@ Example::
     print(f"Extra bytes: {extra}") # Output: Extra bytes: b'\\n\\x0b'
     print(f"Final position: {buf.pos}") # Output: Final position: 7
     print(f"Raw buffer: {buf.get_raw()}") # Output: Raw buffer: bytearray(b'\\x02\\x01\\x02Hi\\n\\x0b\\x00\\x00\\x00')
+    ```
 """
 
-
-
 from __future__ import annotations
 
 from ctypes import create_string_buffer, memset
@@ -102,22 +100,22 @@ class BufferFactory(Protocol): # pragma: no cover
                   is bytes to specify a potentially different final size.
 
         Returns:
-            The created mutable buffer object (e.g., `bytearray`, `ctypes.c_char_Array`).
+            The created mutable buffer object (e.g., [bytearray][] or a ctypes array of characters).
         """
     def clear(self, buffer: Any) -> None:
         """Fill the buffer entirely with null bytes (zeros).
 
-        Argument:
+        Arguments:
             buffer: A memory buffer previously created by this factory's `create()` method.
         """
     def get_raw(self, buffer: Any) -> bytes | bytearray:
-        """Return the buffer's content as a standard `bytes` or `bytearray`.
+        """Return the buffer's content as a standard [bytes][] or [bytearray][].
 
         This method is necessary to provide a consistent way to access the raw
         byte sequence, as the buffer object returned by `create` might be of a
-        different type (e.g., `ctypes` arrays have a `.raw` attribute).
+        different type (e.g., [ctypes][] arrays have a `raw` attribute).
 
-        Argument:
+        Arguments:
             buffer: A memory buffer previously created by this factory's `create()` method.
 
         Returns:
@@ -125,10 +123,10 @@ class BufferFactory(Protocol): # pragma: no cover
         """
 
 class BytesBufferFactory:
-    """Buffer factory using Python's `bytearray` for storage."""
+    """Buffer factory using Python's [bytearray][] for storage."""
     def create(self, init_or_size: int | bytes, size: int | None=None) -> bytearray:
         """This function creates a mutable character buffer. The returned object is a
-        `bytearray`.
+        [bytearray][].
 
         Arguments:
             init_or_size: Must be an integer which specifies the size of the array,
@@ -136,13 +134,13 @@ class BytesBufferFactory:
             size: Size of the array.
 
         Important:
-            Although arguments are the same as for `ctypes.create_string_buffer`,
+            Although arguments are the same as for [ctypes.create_string_buffer][],
             the behavior is different when new buffer is initialized from bytes:
 
             1. If there are more bytes than specified `size`, this function copies only
-               `size` bytes into new buffer. The `~ctypes.create_string_buffer` raises
+               `size` bytes into new buffer. The [ctypes.create_string_buffer][] raises
                an excpetion.
-            2. Unlike `~ctypes.create_string_buffer` when `size` is NOT specified,
+            2. Unlike [ctypes.create_string_buffer][] when `size` is NOT specified,
                the buffer is NOT made one item larger than its length so that the last
                element in the array is a NUL termination character.
         """
@@ -161,10 +159,10 @@ class BytesBufferFactory:
         return buffer
 
 class CTypesBufferFactory:
-    """Buffer factory using `ctypes.create_string_buffer` (array of c_char)."""
+    """Buffer factory using [ctypes.create_string_buffer][] (array of `c_char`)."""
     def create(self, init_or_size: int | bytes, size: int | None=None) -> bytearray:
-        """This function creates a `ctypes` mutable character buffer. The returned object
-        is an array of `ctypes.c_char`.
+        """This function creates a [ctypes][] mutable character buffer. The returned object
+        is an array of [ctypes.c_char][].
 
         Arguments:
             init_or_size: Must be an integer which specifies the size of the array,
@@ -172,13 +170,13 @@ class CTypesBufferFactory:
             size: Size of the array.
 
         Important:
-            Although arguments are the same as for `ctypes.create_string_buffer`,
+            Although arguments are the same as for [ctypes.create_string_buffer][],
             the behavior is different when new buffer is initialized from bytes:
 
             1. If there are more bytes than specified `size`, this function copies only
-               `size` bytes into new buffer. The `~ctypes.create_string_buffer` raises
+               `size` bytes into new buffer. The [ctypes.create_string_buffer][] raises
                an excpetion.
-            2. Unlike `~ctypes.create_string_buffer` when `size` is NOT specified,
+            2. Unlike [ctypes.create_string_buffer][] when `size` is NOT specified,
                the buffer is NOT made one item larger than its length so that the last
                element in the array is a NUL termination character.
         """
@@ -194,7 +192,7 @@ class CTypesBufferFactory:
 
         Arguments:
             buffer: The ctypes buffer.
-            init: The byte value to fill with (default 0).
+            init: The byte value to fill with.
         """
         memset(buffer, init, len(buffer))
     def get_raw(self, buffer: Any) -> bytes | bytearray:
@@ -230,19 +228,19 @@ class MemoryBuffer:
     def __init__(self, init: int | bytes, size: int | None=None, *,
                  factory: type[BufferFactory]=BytesBufferFactory, eof_marker: int | None=None,
                  max_size: int | Sentinel=UNLIMITED, byteorder: ByteOrder=ByteOrder.LITTLE):
-        #: Buffer factory instance used by manager [default: `BytesBufferFactory`].
         self.factory: BufferFactory = factory()
-        #: The memory buffer. The actual data type of buffer depends on `buffer factory`,
-        #: but it must provide direct acces to cells, slices and length like `bytearray`.
+        "Buffer factory instance used by manager [default: `BytesBufferFactory`]."
         self.raw: bytearray = self.factory.create(init, size)
-        #: Current position in buffer, i.e. the next read/writen byte would be at this position.
+        """The memory buffer. The actual data type of buffer depends on `buffer factory`,
+        but it must provide direct acces to cells, slices and length like `bytearray`."""
         self.pos: int = 0
-        #: Value that indicates the end of data. Could be None.
+        "Current position in buffer, i.e. the next read/writen byte would be at this position."
         self.eof_marker: int = eof_marker
-        #: The buffer couldn't grow beyond specified number of bytes [default: `.UNLIMITED`].
+        "Value that indicates the end of data. Could be None."
         self.max_size: int | Sentinel = max_size
-        #: The byte order used to read/write numbers [default: `.LITTLE`].
+        "The buffer couldn't grow beyond specified number of bytes [default: `UNLIMITED`]."
         self.byteorder: ByteOrder = byteorder
+        "The byte order used to read/write numbers [default: `LITTLE`]."
     def _ensure_space(self, size: int) -> None:
         if len(self.raw) < self.pos + size:
             self.resize(self.pos + size)
@@ -282,7 +280,7 @@ class MemoryBuffer:
             return True
         return False
     def get_raw(self) -> bytes | bytearray:
-        """Return the underlying buffer's content as `bytes` or `bytearray`.
+        """Return the underlying buffer's content as [bytes][] or [bytearray][].
 
         Use this method for generic access to the raw buffer content instead of
         accessing the `raw` attribute directly, as the type of `raw` can vary
@@ -321,7 +319,7 @@ class MemoryBuffer:
             size: Value size in bytes.
             signed: Write as signed or unsigned integer.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         self.write(value.to_bytes(size, self.byteorder.value, signed=signed))
@@ -331,7 +329,7 @@ class MemoryBuffer:
         Arguments:
             value: The integer value to write.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         self.write_number(value, 2)
@@ -341,7 +339,7 @@ class MemoryBuffer:
         Arguments:
             value: The integer value to write.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         self.write_number(value, 4)
@@ -351,7 +349,7 @@ class MemoryBuffer:
         Arguments:
             value: The integer value to write.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         self.write_number(value, 8)
@@ -360,10 +358,10 @@ class MemoryBuffer:
 
         Arguments:
             value: The string to write.
-            encoding: Encoding to use (default: 'ascii').
-            errors: Encoding error handling scheme (default: 'strict').
+            encoding: Encoding to use.
+            errors: Encoding error handling scheme.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
             UnicodeEncodeError: If `value` cannot be encoded using `encoding`.
         """
@@ -374,10 +372,10 @@ class MemoryBuffer:
 
         Arguments:
             value: The string to write.
-            encoding: Encoding to use (default: 'ascii').
-            errors: Encoding error handling scheme (default: 'strict').
+            encoding: Encoding to use.
+            errors: Encoding error handling scheme.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         value = value.encode(encoding, errors)
@@ -388,10 +386,10 @@ class MemoryBuffer:
 
         Arguments:
             value: The string to write.
-            encoding: Encoding to use (default: 'ascii').
-            errors: Encoding error handling scheme (default: 'strict').
+            encoding: Encoding to use.
+            errors: Encoding error handling scheme.
 
-        Raise:
+        Raises:
             BufferError: If resizing is needed but exceeds `max_size`.
         """
         value = value.encode(encoding, errors)
@@ -404,7 +402,7 @@ class MemoryBuffer:
 
         Arguments:
             size: Number of bytes to read. If negative, reads all data from the
-                  current position to the end of the buffer (default: -1).
+                  current position to the end of the buffer.
         Returns:
            The bytes read.
 
@@ -417,14 +415,14 @@ class MemoryBuffer:
         result = self.raw[self.pos: self.pos + size]
         self.pos += size
         return result
-    def read_number(self, size: int, *, signed=False) -> int:
+    def read_number(self, size: int, *, signed: bool=False) -> int:
         """Read a number of `size` bytes from current position using `self.byteorder`.
 
         Advances the position by `size`.
 
         Arguments:
             size: The number of bytes representing the number.
-            signed: Whether to interpret the bytes as a signed integer (default: False).
+            signed: Whether to interpret the bytes as a signed integer.
 
         Returns:
            The integer value read.
@@ -462,8 +460,8 @@ class MemoryBuffer:
         Advances the position past the null terminator.
 
         Arguments:
-            encoding: Encoding to use for decoding (default: 'ascii').
-            errors: Decoding error handling scheme (default: 'strict').
+            encoding: Encoding to use for decoding.
+            errors: Decoding error handling scheme.
 
         Returns:
             The decoded string (excluding the null terminator).
@@ -482,8 +480,8 @@ class MemoryBuffer:
         """Read Pascal string (1 byte length followed by string data).
 
         Arguments:
-            encoding: Encoding to use for decoding (default: 'ascii').
-            errors: Decoding error handling scheme (default: 'strict').
+            encoding: Encoding to use for decoding.
+            errors: Decoding error handling scheme.
 
         Returns:
             The decoded string.
@@ -497,8 +495,8 @@ class MemoryBuffer:
         """Read sized string (2 byte length followed by data).
 
         Arguments:
-            encoding: Encoding to use for decoding (default: 'ascii').
-            errors: Decoding error handling scheme (default: 'strict').
+            encoding: Encoding to use for decoding.
+            errors: Decoding error handling scheme.
 
         Returns:
             The decoded string.