binarycookies 2.1.4__tar.gz → 2.2.0__tar.gz

{binarycookies-2.1.4 → binarycookies-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: binarycookies
-Version: 2.1.4
+Version: 2.2.0
 Summary: Python Binary Cookies (de)serializer
 Author: Daniel Tom
 Author-email: d.e.tom89@gmail.com
@@ -10,81 +10,35 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
 Requires-Dist: typer (>=0.12.3,<0.17.0)
 Description-Content-Type: text/markdown
 
 [![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)
+<h1>
+  <img src="docs/bincook.png" width="30" style="vertical-align: middle; margin-right: 10px;">
+  Binary Cookies
+</h1>
 
-# Binary Cookies
+CLI tool and Python library for reading and writing Binary Cookies.
 
-Python library and CLI tool for reading and writing binary cookies files.
+### Requirements
 
-## Requirements
+- Python >= 3.9
 
-- Python 3.9 or higher
-
-## Installation
+### Installation
 ```bash 
 pip install binarycookies
 ```
-If you want to use the parser as CLI, it's recommended to use pipx to install the package in an isolated environment.
-```bash 
-pipx install binarycookies
-```
-
-## Basic Usage CLI
-After installation, you can use the command-line interface to read a binary cookies file:
-
-```bash
-bcparser <path_to_binary_cookies_file>
-```
-Replace <path_to_binary_cookies_file> with the path to the binary cookie file you want to read.
-
-### Basic Usage Python
-
-#### Deserialization
-
-```python
-import binarycookies 
-
-with open("path/to/cookies.binarycookies", "rb") as f:
-    cookies = binarycookies.load(f)
-```
-
-#### Serialization
-
-```python
-import binarycookies 
-
-cookie = {
-    "name": "session_id",
-    "value": "abc123",
-    "url": "https://example.com",
-    "path": "/",
-    "create_datetime": "2023-10-01T12:34:56+00:00",
-    "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "Secure"
-}
-
-with open("path/to/cookies.binarycookies", "wb") as f:
-    binarycookies.dump(cookie, f)
-```
-
-## Output Types
-
-The `bcparser` CLI supports two output types: `json` (default) and `ascii`.
-
-### JSON Output
-
-The `json` output type formats the cookies as a JSON array, making it easy to parse and manipulate programmatically.
 
-Example usage:
+### CLI example:
 ```sh
-bcparser path/to/cookies.binarycookies --output json
+bcparser path/to/cookies.binarycookies
 ```
 
-Example output JSON:
+Output:
 ```json
 [
   {
@@ -108,8 +62,10 @@ Example output JSON:
 ]
 ```
 
+
 ### ASCII Output
-The ascii output type formats the cookies in a simple, line-by-line text format, making it easy to read and pipe to other command-line tools.
+
+`ascii` output is also possible with the --output ascii flag.
 
 Example usage:
 ```sh
@@ -135,9 +91,53 @@ Expires: 2023-12-31T23:59:59+00:00
 Flag: HttpOnly
 ----------------------------------------
 ```
+### Netscape Output
+For `netscape` output use the --output netscape flag.
+Example usage:
+```sh
+bcparser path/to/cookies.binarycookies --output netscape
+```
+
+Example output Netscape:
+```netscape 
+# Netscape HTTP Cookie File
+example.com	FALSE	/	TRUE	1704067199	session_id	abc123
+example.com	FALSE	/account	FALSE	1704067199	user_token	xyz789
+```
+
+### Basic Usage Python
+
+#### Deserialization
+
+```python
+import binarycookies 
+
+with open("path/to/cookies.binarycookies", "rb") as f:
+    cookies = binarycookies.load(f)
+```
+
+#### Serialization
+
+```python
+import binarycookies 
+
+cookie = {
+    "name": "session_id",
+    "value": "abc123",
+    "url": "https://example.com",
+    "path": "/",
+    "create_datetime": "2023-10-01T12:34:56+00:00",
+    "expiry_datetime": "2023-12-31T23:59:59+00:00",
+    "flag": "Secure"
+}
+
+with open("path/to/cookies.binarycookies", "wb") as f:
+    binarycookies.dump(cookie, f)
+```
 
 ### License
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
 ### Contributing
 Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.
+

{binarycookies-2.1.4 → binarycookies-2.2.0}/README.md

@@ -1,74 +1,26 @@
 [![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)
+<h1>
+  <img src="docs/bincook.png" width="30" style="vertical-align: middle; margin-right: 10px;">
+  Binary Cookies
+</h1>
 
-# Binary Cookies
+CLI tool and Python library for reading and writing Binary Cookies.
 
-Python library and CLI tool for reading and writing binary cookies files.
+### Requirements
 
-## Requirements
+- Python >= 3.9
 
-- Python 3.9 or higher
-
-## Installation
+### Installation
 ```bash 
 pip install binarycookies
 ```
-If you want to use the parser as CLI, it's recommended to use pipx to install the package in an isolated environment.
-```bash 
-pipx install binarycookies
-```
-
-## Basic Usage CLI
-After installation, you can use the command-line interface to read a binary cookies file:
-
-```bash
-bcparser <path_to_binary_cookies_file>
-```
-Replace <path_to_binary_cookies_file> with the path to the binary cookie file you want to read.
-
-### Basic Usage Python
-
-#### Deserialization
-
-```python
-import binarycookies 
-
-with open("path/to/cookies.binarycookies", "rb") as f:
-    cookies = binarycookies.load(f)
-```
-
-#### Serialization
-
-```python
-import binarycookies 
-
-cookie = {
-    "name": "session_id",
-    "value": "abc123",
-    "url": "https://example.com",
-    "path": "/",
-    "create_datetime": "2023-10-01T12:34:56+00:00",
-    "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "Secure"
-}
-
-with open("path/to/cookies.binarycookies", "wb") as f:
-    binarycookies.dump(cookie, f)
-```
-
-## Output Types
-
-The `bcparser` CLI supports two output types: `json` (default) and `ascii`.
-
-### JSON Output
 
-The `json` output type formats the cookies as a JSON array, making it easy to parse and manipulate programmatically.
-
-Example usage:
+### CLI example:
 ```sh
-bcparser path/to/cookies.binarycookies --output json
+bcparser path/to/cookies.binarycookies
 ```
 
-Example output JSON:
+Output:
 ```json
 [
   {
@@ -92,8 +44,10 @@ Example output JSON:
 ]
 ```
 
+
 ### ASCII Output
-The ascii output type formats the cookies in a simple, line-by-line text format, making it easy to read and pipe to other command-line tools.
+
+`ascii` output is also possible with the --output ascii flag.
 
 Example usage:
 ```sh
@@ -119,9 +73,52 @@ Expires: 2023-12-31T23:59:59+00:00
 Flag: HttpOnly
 ----------------------------------------
 ```
+### Netscape Output
+For `netscape` output use the --output netscape flag.
+Example usage:
+```sh
+bcparser path/to/cookies.binarycookies --output netscape
+```
+
+Example output Netscape:
+```netscape 
+# Netscape HTTP Cookie File
+example.com	FALSE	/	TRUE	1704067199	session_id	abc123
+example.com	FALSE	/account	FALSE	1704067199	user_token	xyz789
+```
+
+### Basic Usage Python
+
+#### Deserialization
+
+```python
+import binarycookies 
+
+with open("path/to/cookies.binarycookies", "rb") as f:
+    cookies = binarycookies.load(f)
+```
+
+#### Serialization
+
+```python
+import binarycookies 
+
+cookie = {
+    "name": "session_id",
+    "value": "abc123",
+    "url": "https://example.com",
+    "path": "/",
+    "create_datetime": "2023-10-01T12:34:56+00:00",
+    "expiry_datetime": "2023-12-31T23:59:59+00:00",
+    "flag": "Secure"
+}
+
+with open("path/to/cookies.binarycookies", "wb") as f:
+    binarycookies.dump(cookie, f)
+```
 
 ### License
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
 ### Contributing
-Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.
+Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.

{binarycookies-2.1.4 → binarycookies-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binarycookies"
-version = "2.1.4"
+version = "2.2.0"
 description = "Python Binary Cookies (de)serializer"
 authors = ["Daniel Tom <d.e.tom89@gmail.com>"]
 readme = "README.md"
@@ -11,14 +11,25 @@ python = ">=3.8,<4.0"
 typer = ">=0.12.3,<0.17.0"
 pydantic = ">=2.0.0,<3.0.0"
 
-[tool.poetry.scripts]
-bcparser = "binarycookies.__main__:main"
-
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.2.2"
 ruff = ">=0.5.1,<0.8.0"
 pytest-cov = "^5.0.0"
 
+[tool.poetry.group.docs.dependencies]
+mkdocs = "^1.4.2"
+mkdocs-material = "^9.1.4"
+mkdocs-gen-files = ">=0.4,<0.6"
+mkdocs-literate-nav = "^0.6.0"
+mkdocstrings = {extras = ["python"], version = ">=0.20,<0.30"}
+mkautodoc = "^0.2.0"
+pymdown-extensions = "^10.0.1"
+
+[tool.poetry.scripts]
+bcparser = "binarycookies.__main__:main"
+
+
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
@@ -43,7 +54,8 @@ lint.ignore = [
     "RUF012",  # causes failures in pydantic models
     "PLR0911", # for some reason can't ignore this on func definition
     "ISC001",
-    "COM812"
+    "COM812",
+    "T201", # WE want to use print in CLI
 ]
 lint.extend-select = [
     "I",

binarycookies-2.2.0/src/binarycookies/__main__.py

@@ -0,0 +1,38 @@
+import json
+from datetime import datetime
+from typing import Type
+
+import typer
+from rich import print as rprint
+
+from binarycookies import load
+from binarycookies._output_handlers import OUTPUT_HANDLERS, OutputType
+
+
+class DateTimeEncoder(json.JSONEncoder):
+    def default(self, obj: Type) -> str:
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        return super().default(obj)
+
+
+def cli(file_path: str, output: OutputType = OutputType.json):
+    """CLI entrypoint for reading Binary Cookies"""
+    with open(file_path, "rb") as f:
+        cookies = load(f)
+
+    handler = OUTPUT_HANDLERS.get(output)
+    if not handler:
+        rprint(f"[red]Error:[/red] Unsupported output type: {output}")
+        raise typer.Exit(code=1)
+
+    handler(cookies)
+
+
+def main():
+    """CLI entrypoint for reading Binary Cookies"""
+    typer.run(cli)
+
+
+if __name__ == "__main__":
+    main()

{binarycookies-2.1.4 → binarycookies-2.2.0}/src/binarycookies/_deserialize.py

@@ -27,8 +27,19 @@ def interpret_flag(flags: int) -> Flag:
 
 
 def mac_epoch_to_date(epoch: int) -> datetime:
-    """Converts a mac epoch time to a datetime object."""
-    return datetime.fromtimestamp(epoch + 978307200, tz=timezone.utc)
+    """
+    Converts a mac epoch time to a datetime object, handling potential
+    overflows on both 32-bit and 64-bit systems.
+    """
+    # The Mac epoch starts on 2001-01-01, which is 978307200 seconds after the Unix epoch.
+    unix_epoch = epoch + 978307200
+
+    try:
+        return datetime.fromtimestamp(unix_epoch, tz=timezone.utc)
+    except (OverflowError, OSError):
+        # This handles timestamps that are too large for the system's C library,
+        # which can happen for non-expiring cookies or on 32-bit systems (Year 2038 problem).
+        return datetime.max.replace(tzinfo=timezone.utc)
 
 
 def read_string(data: BytesIO, size: int) -> str:
@@ -111,8 +122,12 @@ def _deserialize_page(page: BytesIO) -> List[Cookie]:
 
 def load(bf: BinaryIO) -> List[Cookie]:
     """Deserializes a binary cookie file and returns a list of Cookie objects.
+
     Args:
-        bf (BinaryIO): A binary file object containing the binary cookie data."""
+        bf (BinaryIO): A binary file object containing the binary cookie data.
+    Returns:
+        List[Cookie]: A list of Cookie objects.
+    """
     # Check if the file is empty
     if bf.readable() and bf.read(1) == b"":
         raise BinaryCookiesDecodeError("The file is empty.")

binarycookies-2.2.0/src/binarycookies/_output_handlers.py

@@ -0,0 +1,70 @@
+import json
+from datetime import datetime
+from enum import Enum
+from sys import stdout
+from typing import Callable, List, Type
+
+from rich import print as rprint
+
+from binarycookies._serialize import IS_PYDANTIC_V1
+from binarycookies.models import Cookie
+
+
+class DateTimeEncoder(json.JSONEncoder):
+    def default(self, obj: Type) -> str:
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        return super().default(obj)
+
+
+class OutputType(str, Enum):
+    json = "json"
+    ascii = "ascii"
+    netscape = "netscape"
+
+
+def _output_json(cookies: List[Cookie]):
+    """Outputs cookies in JSON format."""
+    output = [cookie.dict() for cookie in cookies] if IS_PYDANTIC_V1 else [cookie.model_dump() for cookie in cookies]
+    json.dump(output, indent=2, cls=DateTimeEncoder, fp=stdout)
+
+
+def _output_ascii(cookies: List[Cookie]):
+    """Outputs cookies in a human-readable ASCII format."""
+    for cookie in cookies:
+        rprint(f"Name: {cookie.name}")
+        rprint(f"Value: {cookie.value}")
+        rprint(f"URL: {cookie.url}")
+        rprint(f"Path: {cookie.path}")
+        rprint(f"Created: {cookie.create_datetime.isoformat()}")
+        rprint(f"Expires: {cookie.expiry_datetime.isoformat()}")
+        rprint(f"Flag: {cookie.flag.value}")
+        rprint("-" * 40)
+
+
+def _output_netscape(cookies: List[Cookie]):
+    """Outputs cookies in Netscape cookie file format."""
+    # http://www.cookiecentral.com/faq/#3.5
+    print("# Netscape HTTP Cookie File")
+    for cookie in cookies:
+        expiry_ts = int(cookie.expiry_datetime.timestamp())
+        domain = cookie.url
+        print(
+            "%(domain)s\t%(flag)s\t%(path)s\t%(secure)s\t%(expiry)d\t%(name)s\t%(value)s"
+            % {
+                "domain": domain,
+                "flag": str(domain.startswith(".")).upper(),
+                "path": cookie.path,
+                "secure": str("Secure" in cookie.flag.value).upper(),
+                "expiry": expiry_ts,
+                "name": cookie.name,
+                "value": cookie.value,
+            }
+        )
+
+
+OUTPUT_HANDLERS: dict[str, Callable[[List[Cookie]], None]] = {
+    OutputType.json: _output_json,
+    OutputType.ascii: _output_ascii,
+    OutputType.netscape: _output_netscape,
+}

{binarycookies-2.1.4 → binarycookies-2.2.0}/src/binarycookies/_serialize.py

@@ -3,9 +3,13 @@ from io import BufferedWriter, BytesIO
 from struct import pack
 from typing import BinaryIO, Dict, List, Tuple, Union
 
+from pydantic import __version__ as pydantic_version
+
 from binarycookies._deserialize import FLAGS
 from binarycookies.models import BcField, Cookie, CookieFields, FileFields, Format
 
+IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
+
 CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
 
 
@@ -82,9 +86,12 @@ def dumps(cookies: CookiesCollection) -> bytes:
         bytes: The serialized binary cookies data.
     """
     if isinstance(cookies, dict):
-        cookies = [Cookie.model_validate(cookies)]
+        cookies = [Cookie.parse_obj(cookies)] if IS_PYDANTIC_V1 else [Cookie.model_validate(cookies)]
     elif isinstance(cookies, (list, tuple)):
-        cookies = [Cookie.model_validate(cookie) for cookie in cookies]
+        if IS_PYDANTIC_V1:
+            cookies = [Cookie.parse_obj(cookie) for cookie in cookies]
+        else:
+            cookies = [Cookie.model_validate(cookie) for cookie in cookies]
     elif isinstance(cookies, Cookie):
         cookies = [cookies]
     else:

{binarycookies-2.1.4 → binarycookies-2.2.0}/src/binarycookies/parser.py

@@ -6,7 +6,7 @@ from binarycookies._deserialize import load
 from binarycookies.models import Cookie
 
 
-@deprecated("read_binary_cookies_file is deprecated, use binary_cookies_parser.load instead.")
+@deprecated("read_binary_cookies_file is deprecated, use binarycookies.load instead.")
 def read_binary_cookies_file(file_path: str) -> List[Cookie]:
     with open(file_path, "rb") as f:
         return load(f)

binarycookies-2.1.4/setup.py

@@ -1,38 +0,0 @@
-# -*- coding: utf-8 -*-
-from setuptools import setup
-
-package_dir = \
-{'': 'src'}
-
-packages = \
-['binarycookies']
-
-package_data = \
-{'': ['*']}
-
-install_requires = \
-['pydantic>=2.0.0,<3.0.0', 'typer>=0.12.3,<0.17.0']
-
-entry_points = \
-{'console_scripts': ['bcparser = binarycookies.__main__:main']}
-
-setup_kwargs = {
-    'name': 'binarycookies',
-    'version': '2.1.4',
-    'description': 'Python Binary Cookies (de)serializer',
-    'long_description': '[![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)\n\n# Binary Cookies\n\nPython library and CLI tool for reading and writing binary cookies files.\n\n## Requirements\n\n- Python 3.9 or higher\n\n## Installation\n```bash \npip install binarycookies\n```\nIf you want to use the parser as CLI, it\'s recommended to use pipx to install the package in an isolated environment.\n```bash \npipx install binarycookies\n```\n\n## Basic Usage CLI\nAfter installation, you can use the command-line interface to read a binary cookies file:\n\n```bash\nbcparser <path_to_binary_cookies_file>\n```\nReplace <path_to_binary_cookies_file> with the path to the binary cookie file you want to read.\n\n### Basic Usage Python\n\n#### Deserialization\n\n```python\nimport binarycookies \n\nwith open("path/to/cookies.binarycookies", "rb") as f:\n    cookies = binarycookies.load(f)\n```\n\n#### Serialization\n\n```python\nimport binarycookies \n\ncookie = {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n}\n\nwith open("path/to/cookies.binarycookies", "wb") as f:\n    binarycookies.dump(cookie, f)\n```\n\n## Output Types\n\nThe `bcparser` CLI supports two output types: `json` (default) and `ascii`.\n\n### JSON Output\n\nThe `json` output type formats the cookies as a JSON array, making it easy to parse and manipulate programmatically.\n\nExample usage:\n```sh\nbcparser path/to/cookies.binarycookies --output json\n```\n\nExample output JSON:\n```json\n[\n  {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n  },\n  {\n    "name": "user_token",\n    "value": "xyz789",\n    "url": "https://example.com",\n    "path": "/account",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "HttpOnly"\n  }\n]\n```\n\n### ASCII Output\nThe ascii output type formats the cookies in a simple, line-by-line text format, making it easy to read and pipe to other command-line tools.\n\nExample usage:\n```sh\nbcparser path/to/cookies.binarycookies --output ascii\n```\n\nExample output ASCII:\n```text\nName: session_id\nValue: abc123\nURL: https://example.com\nPath: /\nCreated: 2023-10-01T12:34:56+00:00\nExpires: 2023-12-31T23:59:59+00:00\nFlag: Secure\n----------------------------------------\nName: user_token\nValue: xyz789\nURL: https://example.com\nPath: /account\nCreated: 2023-10-01T12:34:56+00:00\nExpires: 2023-12-31T23:59:59+00:00\nFlag: HttpOnly\n----------------------------------------\n```\n\n### License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n### Contributing\nContributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.',
-    'author': 'Daniel Tom',
-    'author_email': 'd.e.tom89@gmail.com',
-    'maintainer': 'None',
-    'maintainer_email': 'None',
-    'url': 'None',
-    'package_dir': package_dir,
-    'packages': packages,
-    'package_data': package_data,
-    'install_requires': install_requires,
-    'entry_points': entry_points,
-    'python_requires': '>=3.8,<4.0',
-}
-
-
-setup(**setup_kwargs)

binarycookies-2.1.4/src/binarycookies/__main__.py

@@ -1,48 +0,0 @@
-import json
-from datetime import datetime
-from enum import Enum
-from typing import Type
-
-import typer
-from rich import print
-
-from binarycookies import load
-
-
-class DateTimeEncoder(json.JSONEncoder):
-    def default(self, obj: Type) -> str:
-        if isinstance(obj, datetime):
-            return obj.isoformat()
-        return super().default(obj)
-
-
-class OutputType(str, Enum):
-    json = "json"
-    ascii = "ascii"
-
-
-def cli(file_path: str, output: str = "json"):
-    """CLI entrypoint for reading Binary Cookies"""
-    with open(file_path, "rb") as f:
-        cookies = load(f)
-    if output == OutputType.json:
-        print(json.dumps([cookie.model_dump() for cookie in cookies], indent=2, cls=DateTimeEncoder))
-    elif output == OutputType.ascii:
-        for cookie in cookies:
-            print(f"Name: {cookie.name}")
-            print(f"Value: {cookie.value}")
-            print(f"URL: {cookie.url}")
-            print(f"Path: {cookie.path}")
-            print(f"Created: {cookie.create_datetime.isoformat()}")
-            print(f"Expires: {cookie.expiry_datetime.isoformat()}")
-            print(f"Flag: {cookie.flag.value}")
-            print("-" * 40)
-
-
-def main():
-    """CLI entrypoint for reading Binary Cookies"""
-    typer.run(cli)
-
-
-if __name__ == "__main__":
-    main()