woffu-client 0.0.1__tar.gz

woffu_client-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marc Palacín
+
+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.

woffu_client-0.0.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: woffu_client
+Version: 0.0.1
+Summary: Woffu API client with access to several endpoints.
+Author-email: Marc Palacín Marfil <marc.palacin@bsc.es>
+License: MIT
+Project-URL: Homepage, https://github.com/ProtossGP32/woffu-client
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tzlocal==5.3.1
+Provides-Extra: dev
+Requires-Dist: pytest==8.1.1; extra == "dev"
+Requires-Dist: pytest-cov==5.0.0; extra == "dev"
+Dynamic: license-file
+
+# woffu-client
+Woffu API client with access to several endpoints.
+
+## Installation
+
+### Development
+
+```bash
+pip install -e .
+```
+
+> TODO: Instructions for pre-built package
+
+## Usage:
+
+```bash
+$ woffu-cli -h
+usage: woffu-cli [-h] [--config CONFIG] [--interactive INTERACTIVE] {download-all-documents,get-status,sign,request-credentials} ...
+
+CLI interface for Woffu API client
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       Authentication file path (default: /home/${USER}/.config/woffu/woffu_auth.json)
+  --interactive INTERACTIVE
+                        Set session as interactive or non-interactive (default: True)
+
+actions:
+  {download-all-documents,get-status,sign,request-credentials}
+    download-all-documents
+                        Download all documents from Woffu
+    get-status          Get current status and current day's total amount of worked hours
+    sign                Send sing in or sign out request based on the '--sign-type' argument
+    request-credentials
+                        Request credentials from Woffu. For non-interactive sessions, set username and password as environment variables WOFFU_USERNAME and WOFFU_PASSWORD.
+```

woffu_client-0.0.1/README.md

@@ -0,0 +1,36 @@
+# woffu-client
+Woffu API client with access to several endpoints.
+
+## Installation
+
+### Development
+
+```bash
+pip install -e .
+```
+
+> TODO: Instructions for pre-built package
+
+## Usage:
+
+```bash
+$ woffu-cli -h
+usage: woffu-cli [-h] [--config CONFIG] [--interactive INTERACTIVE] {download-all-documents,get-status,sign,request-credentials} ...
+
+CLI interface for Woffu API client
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       Authentication file path (default: /home/${USER}/.config/woffu/woffu_auth.json)
+  --interactive INTERACTIVE
+                        Set session as interactive or non-interactive (default: True)
+
+actions:
+  {download-all-documents,get-status,sign,request-credentials}
+    download-all-documents
+                        Download all documents from Woffu
+    get-status          Get current status and current day's total amount of worked hours
+    sign                Send sing in or sign out request based on the '--sign-type' argument
+    request-credentials
+                        Request credentials from Woffu. For non-interactive sessions, set username and password as environment variables WOFFU_USERNAME and WOFFU_PASSWORD.
+```

woffu_client-0.0.1/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "woffu_client"
+version = "0.0.1"
+requires-python = ">=3.10,<3.13"
+description = "Woffu API client with access to several endpoints."
+authors = [{name="Marc Palacín Marfil", email="marc.palacin@bsc.es"}]
+readme = "README.md"
+license = {text = "MIT"}
+dependencies = [
+    "tzlocal==5.3.1"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.1.1",
+    "pytest-cov==5.0.0"
+]
+
+
+[project.urls]
+Homepage = "https://github.com/ProtossGP32/woffu-client"
+
+[project.scripts]
+woffu-cli = "woffu_client.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+branch = true
+omit = [
+    # Omit test directory
+    "./tests/*"
+]
+
+[tool.coverage.report]
+# Regexes for lines to exclude from consideration
+exclude_also = [
+    # Don't complain about missing debug-only code:
+    "def __repr__",
+    "if self\\.debug",
+
+    # Don't complain if tests don't hit defensive assertion code:
+    "raise AssertionError",
+    "raise NotImplementedError",
+
+    # Don't complain if non-runnable code isn't run:
+    "if 0:",
+    "if __name__ == .__main__.:",
+
+    # Don't complain about abstract methods, they aren't run:
+    "@(abc\\.)?abstractmethod",
+    ]
+
+ignore_errors = true
+skip_empty = true
+
+[tool.coverage.html]
+directory = "coverage_html_report"
+
+[tool.twine]
+repository = "pypi"
+
+[tool.twine.repositories.pypi]
+repository = "https://upload.pypi.org/legacy/"
+username = "__token__"
+password = "{env:PYPI_API_TOKEN}"
+
+[tool.twine.repositories.github]
+repository = "https://pypi.pkg.github.com/${OWNER}/"
+username = "{env:GITHUB_ACTOR}"
+password = "{env:GITHUB_TOKEN}"

woffu_client-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

woffu_client-0.0.1/src/woffu_client/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+from .woffu_api_client import WoffuAPIClient
+from .stdrequests_session import Session, HTTPResponse

woffu_client-0.0.1/src/woffu_client/cli.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+import argparse
+import sys
+from pathlib import Path
+from woffu_client import WoffuAPIClient  # adjust import path
+
+DEFAULT_CONFIG = Path.home() / ".config/woffu/woffu_auth.json"
+DEFAULT_OUTPUT_DIR = Path.home() / "Documents/woffu/docs"
+DEFAULT_SUMMARY_REPORTS_DIR = Path.home() / "Documents/woffu/summary_reports"
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="woffu-cli",
+        description="CLI interface for Woffu API client"
+    )
+
+    parser.add_argument(
+        "--config",
+        required=False,
+        type=Path,
+        help=f"Authentication file path (default: {DEFAULT_CONFIG})",
+        default=DEFAULT_CONFIG
+    )
+
+    parser.add_argument(
+        "--non-interactive",
+        required=False,
+        action='store_true',
+        help=f"Set session as non-interactive",
+        default=False
+    )
+
+    subparsers = parser.add_subparsers(title="actions", dest="command", required=True)
+
+    # ---- download_all_files ----
+    dl_parser = subparsers.add_parser(
+        "download-all-documents", help="Download all documents from Woffu"
+    )
+    dl_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=DEFAULT_OUTPUT_DIR,
+        help=f"Directory to save downloaded files (default: {DEFAULT_OUTPUT_DIR})"
+    )
+
+    # ---- get_status ----
+    status_parser = subparsers.add_parser(
+        "get-status", help="Get current status and current day's total amount of worked hours"
+    )
+
+    # ---- sign ----
+    sign_parser = subparsers.add_parser(
+        "sign", help="Send sign in or sign out request based on the '--sign-type' argument"
+    )
+
+    sign_parser.add_argument(
+        "--sign-type",
+        type=str,
+        default="any",
+        help="Sign type to send. It can be either 'in', 'out' or 'any' (default: 'any')"
+    )
+    
+    # ---- get_status ----
+    status_parser = subparsers.add_parser(
+        "request-credentials", help="Request credentials from Woffu. For non-interactive sessions, set username and password as environment variables WOFFU_USERNAME and WOFFU_PASSWORD."
+    )
+
+    # ---- get_status ----
+    summary_report_parser = subparsers.add_parser(
+        "summary-report", help="Summary report of work hours for a given time window"
+    )
+
+    summary_report_parser.add_argument(
+        "--from-date",
+        type=str,
+        required=True,
+        help="Start date of the time window. Format YYYY-mm-dd"
+    )
+
+    summary_report_parser.add_argument(
+        "--to-date",
+        type=str,
+        required=True,
+        help="End date of the time window. Format YYYY-mm-dd"
+    )
+
+    summary_report_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=DEFAULT_SUMMARY_REPORTS_DIR,
+        help=f"Directory to save exported CSV file (default: {DEFAULT_SUMMARY_REPORTS_DIR})"
+    )
+
+
+    args = parser.parse_args()
+
+    # Instantiate client
+    client = WoffuAPIClient(config=args.config, interactive=not args.non_interactive)
+    match args.command:
+        case "download-all-documents":
+            try:
+                args.output_dir.mkdir(parents=True, exist_ok=True)
+                client.download_all_documents(output_dir=args.output_dir)
+                print(f"✅ Files downloaded to {args.output_dir}")
+            except Exception as e:
+                print(f"❌ Error downloading files: {e}", file=sys.stderr)
+                sys.exit(1)
+        case "get-status":
+            try:
+                worked_hours, running_status = client.get_status()
+            except Exception as e:
+                print(f"❌ Error retrieving status: {e}", file=sys.stderr)
+        case "sign":
+            try:
+                _ = client.sign(type=args.sign_type)
+            except Exception as e:
+                print(f"❌ Error sending sign command: {e}", file=sys.stderr)
+        case "request-credentials":
+            try:
+                client._request_credentials()
+                client._save_credentials()
+            except Exception as e:
+                print(f"❌ Error requesting new credentials: {e}", file=sys.stderr)
+        case "summary-report":
+            try:
+                summary_report = client.get_summary_report(
+                    from_date=args.from_date,
+                    to_date=args.to_date,
+                    )
+                client.export_summary_to_csv(
+                    summary_report=summary_report,
+                    from_date=args.from_date,
+                    to_date=args.to_date,
+                    output_path=args.output_dir
+                )
+            except Exception as e:
+                print(f"❌ Error retrieving summary report: {e}", file=sys.stderr)
+        case _:
+            print(f"❌ Unknown command: {args.command}", file=sys.stderr)
+    
+
+if __name__ == "__main__":
+    main()

woffu_client-0.0.1/src/woffu_client/stdrequests_session.py

@@ -0,0 +1,273 @@
+import urllib.request
+import urllib.parse
+import json as jsonlib
+import time
+import asyncio
+import base64
+from typing import Any, Optional, Dict, Union, AsyncGenerator, Tuple, cast, Iterator
+from collections.abc import Iterable
+import http.cookiejar
+from urllib.error import URLError, HTTPError
+
+
+class HTTPResponse:
+    _raw: Any
+    status: int
+    headers: Dict[str, str]
+    _stream: bool
+    _cached_content: Optional[bytes]
+
+    def __init__(self, raw_resp: Any, status: int, headers: Dict[str, str], stream: bool = False) -> None:
+        self._raw = raw_resp
+        self.status = status
+        self.headers = headers
+        self._stream = stream
+        self._cached_content = None
+
+    def text(self) -> str:
+        """Return response body decoded to text respecting charset if any."""
+        encoding = "utf-8"
+        content_type = self.headers.get("Content-Type", "")
+        if "charset=" in content_type:
+            try:
+                enc = content_type.split("charset=")[1].split(";")[0].strip()
+                if enc:
+                    encoding = enc
+            except Exception:
+                pass
+        return self.content().decode(encoding, errors="replace")
+
+    def json(self) -> Any:
+        """Parse response body as JSON."""
+        return jsonlib.loads(self.text())
+
+    def content(self) -> bytes:
+        """Return the entire response body as bytes."""
+        if self._cached_content is None:
+            if self._stream:
+                # Read all at once if stream=True by consuming the iterator
+                self._cached_content = b"".join(self.iter_content())
+            else:
+                self._cached_content = self._raw.read()
+        return cast(bytes, self._cached_content)
+
+    def iter_content(self, chunk_size: Optional[int] = 1024) -> Iterator[bytes]:
+        if self._raw is None:
+            yield b""
+            return
+        
+        if not self._stream:
+            yield self.content()
+            return
+
+        if chunk_size is None:
+            # Read all content at once and yield it once
+            chunk = self._raw.read()
+            if chunk:
+                yield chunk
+            return
+
+        if chunk_size <= 0:
+            # Yield empty bytes and stop
+            yield b""
+            return
+
+        while True:
+            chunk = self._raw.read(chunk_size)
+            if not chunk:
+                break
+            yield chunk
+
+    async def aiter_content(self, chunk_size: Optional[int] = 8192) -> AsyncGenerator[bytes, None]:
+        """Async chunked iterator (reads in thread to avoid blocking event loop)."""
+        # Defensive fallback if chunk_size is None or invalid
+        if chunk_size is None or chunk_size <= 0:
+            chunk_size = 8192
+
+        while True:
+            chunk = await asyncio.to_thread(self._raw.read, chunk_size)
+            if not chunk:
+                break
+            yield chunk
+
+    def close(self) -> None:
+        """Close the underlying raw response if it supports close."""
+        close_method = getattr(self._raw, "close", None)
+        if callable(close_method):
+            close_method()
+
+
+class Session:
+    headers: Dict[str, str]
+    params: Dict[str, str]
+    timeout: int
+    retries: int
+    stream: bool
+    _cookie_jar: http.cookiejar.CookieJar
+    _opener: urllib.request.OpenerDirector
+    opener: urllib.request.OpenerDirector
+
+    def __init__(
+        self,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, str]] = None,
+        timeout: int = 10,
+        retries: int = 3,
+        stream: bool = False,
+    ) -> None:
+        self.headers = dict(headers or {})
+        self.params = dict(params or {})
+        self.timeout = timeout
+        self.retries = retries
+        self.stream = stream
+
+        # Cookie handling
+        self._cookie_jar = http.cookiejar.CookieJar()
+        self._opener = urllib.request.build_opener(
+            urllib.request.HTTPCookieProcessor(self._cookie_jar),
+            urllib.request.HTTPRedirectHandler(),
+        )
+
+        # Allow user to set a custom opener later if desired
+        self.opener = self._opener
+
+    def _apply_auth_header(self, headers: Dict[str, str], auth: Optional[Tuple[str, str]]) -> None:
+        if auth:
+            user, pwd = auth
+            token = base64.b64encode(f"{user}:{pwd}".encode("utf-8")).decode("ascii")
+            headers.setdefault("Authorization", f"Basic {token}")
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, str]] = None,
+        data: Optional[Union[dict, str, bytes]] = None,
+        json: Optional[Any] = None,  # <-- added json parameter
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+        retries: Optional[int] = None,
+        stream: Optional[bool] = None,
+        auth: Optional[Tuple[str, str]] = None,
+    ) -> HTTPResponse:
+        # Merge defaults
+        timeout = self.timeout if timeout is None else timeout
+        retries = self.retries if retries is None else retries
+        stream = self.stream if stream is None else stream
+
+        # Build headers and params
+        final_headers = dict(self.headers)  # session headers
+        if headers:
+            final_headers.update(headers)
+        self._apply_auth_header(final_headers, auth)
+
+        final_params = dict(self.params)
+        if params:
+            final_params.update(params)
+        if final_params:
+            url = url + ("&" if "?" in url else "?") + urllib.parse.urlencode(final_params)
+
+        # Prepare body
+        body_bytes: Optional[bytes] = None
+
+        if json is not None:
+            # JSON mode takes precedence over data
+            final_headers.setdefault("Content-Type", "application/json")
+            body_bytes = jsonlib.dumps(json).encode("utf-8")
+        elif data is not None:
+            if isinstance(data, dict):
+                # Default: form-encoded
+                final_headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+                body_bytes = urllib.parse.urlencode(data).encode("utf-8")
+            elif isinstance(data, str):
+                body_bytes = data.encode("utf-8")
+                final_headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+            elif isinstance(data, (bytes, bytearray, memoryview)):
+                # Accept bytearray and memoryview as raw bytes
+                body_bytes = bytes(data)  # convert to bytes if needed
+            elif hasattr(data, "read") and callable(data.read):
+                # Assume file-like, read bytes
+                body_bytes = data.read()
+                if not isinstance(body_bytes, bytes):
+                    raise TypeError("file-like object's read() must return bytes")
+            elif isinstance(data, Iterable):
+                # Accept iterable of bytes chunks; join them
+                body_bytes = b"".join(data)
+            else:
+                raise TypeError("data must be dict, str, or bytes")
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(retries):
+            try:
+                req = urllib.request.Request(
+                    url, data=body_bytes, headers=final_headers, method=method.upper()
+                )
+                raw_resp = self.opener.open(req, timeout=timeout)
+                return HTTPResponse(raw_resp, raw_resp.getcode(), dict(raw_resp.getheaders()), stream=stream)
+            except (HTTPError, URLError, OSError) as e:
+                last_exc = e
+                if isinstance(e, HTTPError):
+                    raw_resp = cast(Any, e)
+                    return HTTPResponse(raw_resp, e.code, dict(e.headers or {}), stream=stream)
+                if attempt < retries - 1:
+                    time.sleep(1)
+                    continue
+                raise last_exc
+
+        # Defensive fallback (should never reach here)
+        raise RuntimeError("Request failed unexpectedly without raising an exception")
+
+    # Convenience sync methods
+    def get(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return self.request("POST", url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return self.request("PUT", url, **kwargs)
+
+    def patch(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return self.request("PATCH", url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return self.request("DELETE", url, **kwargs)
+
+    # Async wrappers using asyncio.to_thread to avoid blocking the event loop
+    async def async_request(self, method: str, url: str, **kwargs: Any) -> HTTPResponse:
+        return await asyncio.to_thread(self.request, method, url, **kwargs)
+
+    async def async_get(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return await self.async_request("GET", url, **kwargs)
+
+    async def async_post(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return await self.async_request("POST", url, **kwargs)
+
+    async def async_put(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return await self.async_request("PUT", url, **kwargs)
+
+    async def async_patch(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return await self.async_request("PATCH", url, **kwargs)
+
+    async def async_delete(self, url: str, **kwargs: Any) -> HTTPResponse:
+        return await self.async_request("DELETE", url, **kwargs)
+
+    # Context manager support
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, exc_type: Optional[type], exc: Optional[BaseException], tb: Optional[Any]) -> bool:
+        # nothing special to close; cookiejar/opener don't need explicit close
+        return False
+
+    def close(self) -> None:
+        """
+        Close the session by clearing cookies and closing any underlying resources.
+        This is just for API consistency, this isn't needed if using a Context manager"""
+        # Clear all cookies
+        self._cookie_jar.clear()
+
+        # Try to close the opener if it has a close method (some custom openers might)
+        close_method = getattr(self.opener, "close", None)
+        if callable(close_method):
+            close_method()