ghnova 0.3.0__py3-none-any.whl

ghnova/user/user.py

@@ -0,0 +1,285 @@
+"""GitHub User resource."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from requests import Response
+
+from ghnova.resource.resource import Resource
+from ghnova.user.base import BaseUser
+from ghnova.utils.response import process_response_with_last_modified
+
+
+class User(BaseUser, Resource):
+    """GitHub User resource."""
+
+    def _get_user(
+        self,
+        username: str | None = None,
+        account_id: int | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> Response:
+        """Get user information.
+
+        Args:
+            username: The username of the user to retrieve. If None, retrieves the authenticated user.
+            account_id: The account ID of the user to retrieve. If None, retrieves by username.
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        endpoint, kwargs = self._get_user_helper(username=username, account_id=account_id, **kwargs)
+        return self._get(endpoint=endpoint, etag=etag, last_modified=last_modified, **kwargs)
+
+    def get_user(
+        self,
+        username: str | None = None,
+        account_id: int | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[dict[str, Any], int, str | None, str | None]:
+        """Get user information.
+
+        Args:
+            username: The username of the user to retrieve. If None, retrieves the authenticated user.
+            account_id: The account ID of the user to retrieve. If None, retrieves by username.
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A dictionary with user information (empty if 304 Not Modified).
+                - The HTTP status code.
+                - The ETag value from the response headers (if present).
+                - The Last-Modified timestamp from the response headers (if present).
+
+        """
+        response = self._get_user(
+            username=username, account_id=account_id, etag=etag, last_modified=last_modified, **kwargs
+        )
+        data, status_code, etag_value, last_modified_value = process_response_with_last_modified(response)
+        data = cast(dict[str, Any], data)
+        return data, status_code, etag_value, last_modified_value
+
+    def _update_user(  # noqa: PLR0913
+        self,
+        name: str | None = None,
+        email: str | None = None,
+        blog: str | None = None,
+        twitter_username: str | None = None,
+        company: str | None = None,
+        location: str | None = None,
+        hireable: bool | None = None,
+        bio: str | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> Response:
+        """Update the authenticated user's information.
+
+        Args:
+            name: The name of the user.
+            email: The email of the user.
+            blog: The blog URL of the user.
+            twitter_username: The Twitter username of the user.
+            company: The company of the user.
+            location: The location of the user.
+            hireable: The hireable status of the user.
+            bio: The bio of the user.
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        endpoint, payload, kwargs = self._update_user_helper(
+            name=name,
+            email=email,
+            blog=blog,
+            twitter_username=twitter_username,
+            company=company,
+            location=location,
+            hireable=hireable,
+            bio=bio,
+            **kwargs,
+        )
+        return self._patch(endpoint=endpoint, json=payload, etag=etag, last_modified=last_modified, **kwargs)
+
+    def update_user(  # noqa: PLR0913
+        self,
+        name: str | None = None,
+        email: str | None = None,
+        blog: str | None = None,
+        twitter_username: str | None = None,
+        company: str | None = None,
+        location: str | None = None,
+        hireable: bool | None = None,
+        bio: str | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[dict[str, Any], int, str | None, str | None]:
+        """Update the authenticated user's information.
+
+        Args:
+            name: The name of the user.
+            email: The email of the user.
+            blog: The blog URL of the user.
+            twitter_username: The Twitter username of the user.
+            company: The company of the user.
+            location: The location of the user.
+            hireable: The hireable status of the user.
+            bio: The bio of the user.
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A dictionary with updated user information (empty if 304 Not Modified).
+                - The HTTP status code.
+                - The ETag value from the response headers (if present).
+                - The Last-Modified timestamp from the response headers (if present).
+
+        """
+        response = self._update_user(
+            name=name,
+            email=email,
+            blog=blog,
+            twitter_username=twitter_username,
+            company=company,
+            location=location,
+            hireable=hireable,
+            bio=bio,
+            etag=etag,
+            last_modified=last_modified,
+            **kwargs,
+        )
+        data, status_code, etag_value, last_modified_value = process_response_with_last_modified(response)
+        data = cast(dict[str, Any], data)
+
+        return data, status_code, etag_value, last_modified_value
+
+    def _list_users(
+        self,
+        since: int | None = None,
+        per_page: int | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> Response:
+        """List all users.
+
+        Args:
+            since: The integer ID of the last User that you've seen.
+            per_page: The number of results per page (max 100).
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A response object.
+
+        """
+        endpoint, params, kwargs = self._list_users_helper(since=since, per_page=per_page, **kwargs)
+        return self._get(endpoint=endpoint, params=params, etag=etag, last_modified=last_modified, **kwargs)
+
+    def list_users(
+        self,
+        since: int | None = None,
+        per_page: int | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[list[dict[str, Any]], int, str | None, str | None]:
+        """List all users.
+
+        Args:
+            since: The integer ID of the last User that you've seen.
+            per_page: The number of results per page (max 100).
+            etag: The ETag value for conditional requests.
+            last_modified: The Last-Modified timestamp for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A list of user dictionaries (empty if 304 Not Modified).
+                - The HTTP status code.
+                - The ETag value from the response headers (if present).
+                - The Last-Modified timestamp from the response headers (if present).
+
+        """
+        response = self._list_users(since=since, per_page=per_page, etag=etag, last_modified=last_modified, **kwargs)
+        data, status_code, etag_value, last_modified_value = process_response_with_last_modified(response)
+        if status_code == 304:  # noqa: PLR2004
+            data = []
+        return cast(list[dict[str, Any]], data), status_code, etag_value, last_modified_value
+
+    def _get_contextual_information(
+        self,
+        username: str,
+        subject_type: str | None = None,
+        subject_id: str | None = None,
+        **kwargs: Any,
+    ) -> Response:
+        """Get contextual information about a user.
+
+        Args:
+            username: The username of the user.
+            subject_type: The type of subject for the hovercard.
+            subject_id: The ID of the subject for the hovercard.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        endpoint, params, kwargs = self._get_contextual_information_helper(
+            username=username, subject_type=subject_type, subject_id=subject_id, **kwargs
+        )
+        return self._get(endpoint=endpoint, params=params, **kwargs)
+
+    def get_contextual_information(
+        self,
+        username: str,
+        subject_type: str | None = None,
+        subject_id: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[dict[str, Any], int, str | None, str | None]:
+        """Get contextual information about a user.
+
+        Args:
+            username: The username of the user.
+            subject_type: The type of subject for the hovercard.
+            subject_id: The ID of the subject for the hovercard.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A dictionary with contextual information about the user.
+                - The HTTP status code.
+                - The ETag value from the response headers (if present).
+                - The Last-Modified timestamp from the response headers (if present).
+
+        """
+        response = self._get_contextual_information(
+            username=username, subject_type=subject_type, subject_id=subject_id, **kwargs
+        )
+        data, status_code, etag_value, last_modified_value = process_response_with_last_modified(response)
+        data = cast(dict[str, Any], data)
+        return data, status_code, etag_value, last_modified_value

ghnova/utils/__init__.py

@@ -0,0 +1,16 @@
+"""Utility functions for the ghnova package."""
+
+from __future__ import annotations
+
+from ghnova.utils.log import get_version_information, setup_logger
+from ghnova.utils.response import (
+    process_async_response_with_last_modified,
+    process_response_with_last_modified,
+)
+
+__all__ = [
+    "get_version_information",
+    "process_async_response_with_last_modified",
+    "process_response_with_last_modified",
+    "setup_logger",
+]

ghnova/utils/log.py

@@ -0,0 +1,70 @@
+"""Utility functions for logging."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from ghnova.version import __version__
+
+
+def get_version_information() -> str:
+    """Get the version information.
+
+    Returns:
+        str: Version information.
+
+    """
+    return __version__
+
+
+def setup_logger(
+    outdir: str = ".", label: str | None = None, log_level: str | int = "INFO", print_version: bool = False
+) -> None:
+    """Set up logging output: call at the start of the script to use.
+
+    Args:
+        outdir: Output directory for log file.
+        label: Label for log file name. If None, no log file is created.
+        log_level: Logging level as string or integer.
+        print_version: Whether to print version information to the log.
+
+    """
+    if isinstance(log_level, str):
+        try:
+            level = getattr(logging, log_level.upper())
+        except AttributeError as e:
+            raise ValueError(f"log_level {log_level} not understood") from e
+    else:
+        level = int(log_level)
+
+    logger = logging.getLogger("ghnova")
+    logger.propagate = False
+    logger.setLevel(level)
+
+    if not any(
+        isinstance(h, logging.StreamHandler) and not isinstance(h, logging.FileHandler) for h in logger.handlers
+    ):
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(name)s %(levelname)-8s: %(message)s", datefmt="%H:%M")
+        )
+        stream_handler.setLevel(level)
+        logger.addHandler(stream_handler)
+
+    if not any(isinstance(h, logging.FileHandler) for h in logger.handlers) and label:
+        outdir_path = Path(outdir)
+        outdir_path.mkdir(parents=True, exist_ok=True)
+        log_file = outdir_path / f"{label}.log"
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-8s: %(message)s", datefmt="%H:%M"))
+
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+
+    for handler in logger.handlers:
+        handler.setLevel(level)
+
+    if print_version:
+        version = get_version_information()
+        logger.info("Running ghnova version: %s", version)

ghnova/utils/response.py

@@ -0,0 +1,67 @@
+"""Response processing utilities with Last-Modified handling."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import ClientResponse, ContentTypeError
+from requests import Response
+
+logger = logging.getLogger("ghnova")
+
+
+def process_response_with_last_modified(
+    response: Response,
+) -> tuple[dict[str, Any] | list[dict[str, Any]], int, str | None, str | None]:
+    """Process an HTTP response and extract data, status, ETag, and Last-Modified.
+
+    Args:
+        response: The HTTP response object.
+
+    Returns:
+        A tuple containing the response data, status code, ETag, and Last-Modified.
+
+    """
+    status_code = response.status_code
+    etag = response.headers.get("ETag", None)
+    last_modified = response.headers.get("Last-Modified", None)
+    if status_code == 204:  # noqa: PLR2004
+        data = {}
+    elif 200 <= status_code < 300:  # noqa: PLR2004
+        try:
+            data = response.json()
+        except ValueError as e:
+            logger.error("Failed to parse JSON response: %s", e)
+            data = {}
+    else:
+        data = {}
+    return data, status_code, etag, last_modified
+
+
+async def process_async_response_with_last_modified(
+    response: ClientResponse,
+) -> tuple[dict[str, Any] | list[dict[str, Any]], int, str | None, str | None]:
+    """Process an asynchronous HTTP response and extract data, status, ETag, and Last-Modified.
+
+    Args:
+        response: The asynchronous HTTP response object.
+
+    Returns:
+        A tuple containing the response data, status code, ETag, and Last-Modified.
+
+    """
+    status_code = response.status
+    etag = response.headers.get("ETag", None)
+    last_modified = response.headers.get("Last-Modified", None)
+    if status_code == 204:  # noqa: PLR2004
+        data = {}
+    elif 200 <= status_code < 300:  # noqa: PLR2004
+        try:
+            data = await response.json()
+        except (ValueError, ContentTypeError) as e:
+            logger.error("Failed to parse JSON response: %s", e)
+            data = {}
+    else:
+        data = {}
+    return data, status_code, etag, last_modified

ghnova/version.py

@@ -0,0 +1,11 @@
+"""A script to infer the version number from the metadata."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ghnova")
+except PackageNotFoundError:
+    # Fallback for source checkouts or environments without installed metadata.
+    __version__ = "0+unknown"

ghnova-0.3.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: ghnova
+Version: 0.3.0
+Summary: A Python package for interacting with the GitHub API, offering a simple interface to access repositories, users, organizations, issues, and more for automation and data management.
+Project-URL: Documentation, https://isaac-cf-wong.github.io/ghnova
+Project-URL: Source, https://github.com/isaac-cf-wong/ghnova
+Project-URL: Tracker, https://github.com/isaac-cf-wong/ghnova/issues
+Project-URL: Home, https://github.com/isaac-cf-wong/ghnova
+Project-URL: Release Notes, https://github.com/isaac-cf-wong/ghnova/releases
+Author-email: "Isaac C. F. Wong" <isaac.cf.wong@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: aiohttp==3.13.3
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: typer==0.21.1
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike; extra == 'docs'
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-gen-files; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-section-index; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: bandit[toml]==1.9.3; extra == 'test'
+Requires-Dist: black==26.1.0; extra == 'test'
+Requires-Dist: check-manifest==0.51; extra == 'test'
+Requires-Dist: flake8; extra == 'test'
+Requires-Dist: flake8-bugbear==25.11.29; extra == 'test'
+Requires-Dist: flake8-docstrings; extra == 'test'
+Requires-Dist: flake8-formatter-junit-xml; extra == 'test'
+Requires-Dist: flake8-pyproject; extra == 'test'
+Requires-Dist: pre-commit==4.5.1; extra == 'test'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'test'
+Requires-Dist: pytest-cov==7.0.0; extra == 'test'
+Requires-Dist: pytest-github-actions-annotate-failures; extra == 'test'
+Requires-Dist: pytest-mock<3.15.2; extra == 'test'
+Requires-Dist: pytest-runner; extra == 'test'
+Requires-Dist: pytest==9.0.2; extra == 'test'
+Requires-Dist: shellcheck-py==0.11.0.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ghnova
+
+[![Python CI](https://github.com/isaac-cf-wong/ghnova/actions/workflows/CI.yml/badge.svg)](https://github.com/isaac-cf-wong/ghnova/actions/workflows/CI.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/isaac-cf-wong/ghnova/main.svg)](https://results.pre-commit.ci/latest/github/isaac-cf-wong/ghnova/main)
+[![Documentation Status](https://github.com/isaac-cf-wong/ghnova/actions/workflows/documentation.yml/badge.svg)](https://isaac-cf-wong.github.io/ghnova/)
+[![codecov](https://codecov.io/gh/isaac-cf-wong/ghnova/graph/badge.svg?token=COF8341N60)](https://codecov.io/gh/isaac-cf-wong/ghnova)
+[![PyPI Version](https://img.shields.io/pypi/v/ghnova)](https://pypi.org/project/ghnova/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ghnova)](https://pypi.org/project/ghnova/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![DOI](https://zenodo.org/badge/1136398756.svg)](https://doi.org/10.5281/zenodo.18290200)
+
+**Note:** This project is still in progress. The promised features are not fully ready yet, and APIs are subject to change.
+
+A Python package for interacting with the GitHub API.
+This package provides a simple and intuitive interface to access
+GitHub repositories, users, organizations, issues, and more,
+enabling seamless integration with GitHub instances for automation, data retrieval, and management tasks.
+
+## Features
+
+Full API Coverage: Access to repositories, users, organizations, issues, pull requests, and more.
+
+- Easy Authentication: Support for token-based authentication.
+- Asynchronous Support: Built with async/await for non-blocking operations.
+- Type Hints: Full type annotations for better IDE support and code reliability.
+- Comprehensive Documentation: Detailed guides and API reference.
+- Command-Line Interface: Interact with the GitHub API directly from the terminal for
+  quick, scriptable operations without writing code.
+
+## Installation
+
+We recommend using `uv` to manage virtual environments for installing `ghnova`.
+
+If you don't have `uv` installed, you can install it with pip. See the project pages for more details:
+
+- Install via pip: `pip install --upgrade pip && pip install uv`
+- Project pages: [uv on PyPI](https://pypi.org/project/uv/) | [uv on GitHub](https://github.com/astral-sh/uv)
+- Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)
+
+### Requirements
+
+- Python 3.10 or higher
+- Operating System: Linux, macOS, or Windows
+
+### Install from PyPI
+
+The recommended way to install `ghnova` is from PyPI:
+
+```bash
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install ghnova
+```
+
+#### Optional Dependencies
+
+For development or specific features:
+
+```bash
+# Development dependencies (testing, linting, etc.)
+uv pip install ghnova[dev]
+
+# Documentation dependencies
+uv pip install ghnova[docs]
+
+# All dependencies
+uv pip install ghnova[dev,docs]
+```
+
+### Install from Source
+
+For the latest development version:
+
+```bash
+git clone git@github.com:isaac-cf-wong/ghnova.git
+cd ghnova
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install .
+```
+
+#### Development Installation
+
+To set up for development:
+
+```bash
+git clone git@github.com:isaac-cf-wong/ghnova.git
+cd ghnova
+
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install ".[dev]"
+
+# Install the commitlint dependencies
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+### Verify Installation
+
+Check that `ghnova` is installed correctly:
+
+```bash
+ghnova --help
+```
+
+```bash
+python -c "import ghnova; print(ghnova.__version__)"
+```
+
+## Release Schedule
+
+Releases follow a fixed schedule: every Tuesday at 00:00 UTC,
+unless an emergent bugfix is required.
+This ensures predictable updates while allowing flexibility for critical issues.
+Users can view upcoming changes in the draft release on the
+[GitHub Releases page](https://github.com/isaac-cf-wong/ghnova/releases).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For questions, issues, or contributions, please:
+
+- Check the [documentation](https://isaac-cf-wong.github.io/ghnova/)
+- Open an issue on [GitHub](https://github.com/isaac-cf-wong/ghnova/issues)
+- Join our [discussions](https://github.com/isaac-cf-wong/ghnova/discussions)
+
+## Changelog
+
+See [Release Notes](https://github.com/isaac-cf-wong/ghnova/releases) for version history.