hardpycover 0.1.0__tar.gz

hardpycover-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: hardpycover
+Version: 0.1.0
+Summary: Hardcover API wrapper for Python
+Keywords: hardcover,api,wrapper,graphql
+License-Expression: MIT
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: urllib3>=2.4.0
+Requires-Dist: sgqlc ; extra == 'with-sgql'
+Maintainer: Jay Cruz
+Maintainer-email: Jay Cruz <jccruz009@yahoo.com>
+Requires-Python: >=3.11
+Provides-Extra: with-sgql
+Description-Content-Type: text/markdown
+
+## hardcoverpy
+
+Simplified API Wrapper for Hardcover, written in Python.
+
+### Installation
+
+```
+pip install hardcoverpy
+```
+
+```
+uv add hardcoverpy
+```
+
+This is an API wrapper for the Hardcover API made usable in Python.
+
+### Checklists
+*To be checked off before updating visibility*
+
+**Task list**
+1. Create more comprehensive README.md file
+2. Rewrite the querying script and pattern it after the `sgqlc` operations file.
+
+**Important**
+- [x] Licensing file
+- [ ] Installation & about guide
+- [x] Sufficient `pyproject.toml` file
+
+### Development
+
+_Ruff_
+```zsh
+ruff check
+```
+
+##### References
+- This project will primarily be built off of the `praw` and `prawcore` repository
+- The same ownership rights exist for this as anything on the site. You own your data. This means you can't use the API to access and use someone elses data. 

hardpycover-0.1.0/README.md

@@ -0,0 +1,38 @@
+## hardcoverpy
+
+Simplified API Wrapper for Hardcover, written in Python.
+
+### Installation
+
+```
+pip install hardcoverpy
+```
+
+```
+uv add hardcoverpy
+```
+
+This is an API wrapper for the Hardcover API made usable in Python.
+
+### Checklists
+*To be checked off before updating visibility*
+
+**Task list**
+1. Create more comprehensive README.md file
+2. Rewrite the querying script and pattern it after the `sgqlc` operations file.
+
+**Important**
+- [x] Licensing file
+- [ ] Installation & about guide
+- [x] Sufficient `pyproject.toml` file
+
+### Development
+
+_Ruff_
+```zsh
+ruff check
+```
+
+##### References
+- This project will primarily be built off of the `praw` and `prawcore` repository
+- The same ownership rights exist for this as anything on the site. You own your data. This means you can't use the API to access and use someone elses data. 

hardpycover-0.1.0/hardcoverpy/__init__.py

@@ -0,0 +1,8 @@
+from .main import Hardcover
+
+__version__ = "1.0.0"
+__author__ = "Jay Cruz"
+
+__all__ = [
+  "Hardcover"
+]

hardpycover-0.1.0/hardcoverpy/classes/__init__.py

@@ -0,0 +1,15 @@
+from .author import Author
+from .userbooks import UserBook
+from .user import User
+from .search import Search
+from .user_stats import UserBooksAggregate
+from .publishers import Publisher
+
+__all__ = [
+  "Author",
+  "User",
+  "UserBook",
+  "UserBooksAggregate",
+  "Publisher",
+  "Search"
+]

hardpycover-0.1.0/hardcoverpy/classes/author.py

@@ -0,0 +1,34 @@
+from typing import Optional, Dict, List
+from datetime import date
+from pydantic import BaseModel
+
+from .image import CachedImage
+from .utils import Identifiers, Link
+
+class Author(BaseModel):
+  alternate_names: Optional[List[str]] = None
+  alias_id: Optional[int] = None
+  bio: Optional[str] = None
+  books_count: Optional[int] = None
+  born_date: Optional[date] = None
+  born_year: Optional[int] = None
+  cached_image: Optional[CachedImage] = None
+  canonical_id: Optional[int] = None
+  death_date: Optional[date] = None
+  death_year: Optional[int] = None
+  gender_id: Optional[int] = None
+  id: Optional[int] = None
+  identifiers: Optional[Identifiers] = None
+  image_id: Optional[int] = None
+  is_bipoc: Optional[bool] = None
+  is_lgbtq: Optional[bool] = None
+  links: Optional[List[Link]] = None
+  location: Optional[str] = None
+  locked: Optional[bool] = None
+  name: Optional[str] = None
+  name_personal: Optional[str] = None
+  slug: Optional[str] = None
+  state: Optional[str] = None
+  title: Optional[str] = None
+  user_id: Optional[int] = None
+  users_count: Optional[int] = None

hardpycover-0.1.0/hardcoverpy/classes/book_categories.py

@@ -0,0 +1,6 @@
+from typing import Optional
+from pydantic import BaseModel
+
+class BookCategory(BaseModel):
+  id: Optional[int] = None
+  name: Optional[str] = None

hardpycover-0.1.0/hardcoverpy/classes/book_characters.py

@@ -0,0 +1,15 @@
+from typing import Optional
+from pydantic import BaseModel
+
+from .characters import Character
+from .books import Book
+
+class BookCharacter(BaseModel):
+  id: Optional[int] = None
+  book: Optional[Book] = None
+  book_id: Optional[int] = None
+  character: Optional[Character] = None
+  character_id: Optional[int] = None
+  only_mentioned: Optional[bool] = None
+  position: Optional[int] = None
+  spoiler: Optional[bool] = None

hardpycover-0.1.0/hardcoverpy/classes/books.py

@@ -0,0 +1,35 @@
+from typing import Optional, Literal, List
+from datetime import datetime, date
+from pydantic import BaseModel
+
+class RatingsDistribution(BaseModel):
+  count: int
+  rating: int
+
+class Book(BaseModel):
+  id: Optional[int] = None
+  image_id: Optional[int] = None
+  description: Optional[str] = None
+  default_physical_edition_id: Optional[int] = None
+  default_ebook_edition_id: Optional[int] = None
+  default_cover_edition_id: Optional[int] = None
+  default_audio_edition_id: Optional[int] = None
+  created_by_user_id: Optional[int] = None
+  book_category_id: Optional[int] = None
+  users_read_count: Optional[int] = None
+  users_count: Optional[int] = None
+  user_added: Optional[bool] = None
+  updated_at: Optional[datetime] = None
+  title: Optional[str] = None
+  subtitle: Optional[str] = None
+  state: Optional[Literal['error', 'pending', 'normalized', 'duplicate']] = None # This is a Literal but we need to confirm w/c values
+  slug: Optional[str] = None
+  ratings_distribution: Optional[List[RatingsDistribution]] = None
+  ratings_count: Optional[int] = None
+  rating: Optional[int | float] = None
+  prompts_count: Optional[int] = None
+  release_date: Optional[date] = None
+  release_year: Optional[int] = None
+  reviews_count: Optional[int] = None
+  users_count: Optional[int] = None
+  users_read_count: Optional[int] = None

hardpycover-0.1.0/hardcoverpy/classes/characters.py

@@ -0,0 +1,21 @@
+from typing import Optional, Literal
+from datetime import datetime
+from pydantic import BaseModel
+
+class Character(BaseModel):
+  id: Optional[int] = None
+  name: Optional[str] = None
+  biography: Optional[str] = None
+  books_count: Optional[int] = None
+  canonical_books_count: Optional[int] = None
+  created_at: Optional[datetime] = None
+  updated_at: Optional[datetime] = None
+  has_disability: Optional[bool] = None
+  is_lgbtq: Optional[bool] = None
+  is_poc: Optional[bool] = None
+  image_id: Optional[str] = None
+  state: Optional[str] = None
+  slug: Optional[str] = None
+  object_type: Optional[Literal['Character']] = None
+  gender_id: Optional[int] = None
+  user_id: Optional[str] = None

hardpycover-0.1.0/hardcoverpy/classes/contributors.py

@@ -0,0 +1,23 @@
+from typing import Optional, Literal
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict
+
+from .author import Author
+
+class Contributor(BaseModel):
+  author_id: Optional[int] = None
+  contributable_type: Optional[str] = None # Could be a literal
+  contributable_id: Optional[int] = None
+  contribution: Optional[str] = None # Could be literal
+  created_at: Optional[datetime] = None
+  id: int
+  updated_at: Optional[datetime] = None
+
+class CachedContributor(BaseModel):
+  author: Optional[Author] = None
+  contribution: Optional[str] = None
+
+
+# NOTE: list of contribution literals
+# book, afterword, design, ...
+# null, Contributor, Translator, translator

hardpycover-0.1.0/hardcoverpy/classes/editions.py

@@ -0,0 +1,33 @@
+from datetime import datetime, date
+from typing import Optional, Literal
+from pydantic import BaseModel
+
+from .language import Language
+from .publishers import Publisher
+
+class Edition(BaseModel):
+  title: Optional[str] = None
+  subtitle: Optional[str] = None
+  state: Optional[str] = None # normalized, duplicate, ???
+  score: Optional[int] = None
+  edition: Optional[str] = None
+  edition_format: Optional[str] = None
+  edition_information: Optional[str] = None
+  language_id: Optional[int] = None
+  language: Optional[Language] = None
+  country_id: Optional[int] = None
+  image_id: Optional[int] = None
+  publisher_id: Optional[int] = None
+  publisher: Optional[Publisher] = None
+  pages: Optional[int] = None
+  isbn_10: Optional[str] = None
+  isbn_13: Optional[str] = None
+  lists_count: Optional[int] = None
+  object_type: Optional[Literal['Edition']] = None
+  release_year: Optional[int] = None
+  release_date: Optional[date] = None
+  users_count: Optional[int] = None
+  users_read_count: Optional[int] = None
+  created_at: Optional[datetime] = None
+  updated_at: Optional[datetime] = None
+  # normalized_at: Optional[datetime] = None

hardpycover-0.1.0/hardcoverpy/classes/image.py

@@ -0,0 +1,16 @@
+from typing import Optional, List
+from pydantic import BaseModel
+
+class Image(BaseModel):
+  color: Optional[str] = None
+  colors: Optional[List[str]] = None
+  height: Optional[int] = None
+  imageable_id: Optional[int] = None
+  id: Optional[int] = None
+  imageable_type: Optional[str] = None
+  ratio: Optional[int] = None
+  url: Optional[str] = None
+  width: Optional[int] = None
+
+class CachedImage(Image):
+  pass

hardpycover-0.1.0/hardcoverpy/classes/language.py

@@ -0,0 +1,8 @@
+from typing import Optional
+from pydantic import BaseModel
+
+class Language(BaseModel):
+  code2: Optional[str] = None
+  code3: Optional[str] = None
+  id: Optional[int] = None
+  language: Optional[str] = None

hardpycover-0.1.0/hardcoverpy/classes/publishers.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel
+
+class Publisher(BaseModel):
+  id: Optional[int] = None,
+  created_at: Optional[datetime] = None
+  updated_at: Optional[datetime] = None
+  slug: Optional[str] = None
+  name: Optional[str] = None
+  editions_count: Optional[int] = None
+
+class ParentPublisher(Publisher):
+  parent_publisher: Optional[Publisher] = None

hardpycover-0.1.0/hardcoverpy/classes/search.py

@@ -0,0 +1,29 @@
+from .books import Book
+from .utils import TextMatchInfo
+from typing import Optional
+from pydantic import BaseModel
+
+# Fixed values:
+# page = 1; per_page = 25
+
+# NOTE: exempted fields: highlight and highlights
+class SearchHits(BaseModel):
+  document: Optional[Book] = None
+  text_match: Optional[int] = None
+  text_match_info: Optional[TextMatchInfo] = None
+
+class SearchBookResults(BaseModel):
+  facet_counts: Optional[list] = None
+  found: Optional[int] = None
+  hits: Optional[list[SearchHits]] = None
+
+# NOTE: current search focuses on book
+class Search(BaseModel):
+  error: Optional[str] = None
+  ids: Optional[list[int]] = None
+  page: Optional[int] = None
+  per_page: Optional[int] = None
+  query_type: Optional[str] = None # GraphQL returns this as "Book" by default
+  results: Optional[SearchBookResults] = None
+
+# NOTE: for query_type; "Author" is also an appropriate field

hardpycover-0.1.0/hardcoverpy/classes/user.py

@@ -0,0 +1,27 @@
+from typing import Optional, Literal, List
+from datetime import datetime
+from pydantic import BaseModel
+from .utils import CachedImage
+
+# NOTE: expand the User class accordingly
+class User(BaseModel):
+  id: Optional[int] = None
+  bio: Optional[str] = None
+  cached_image: Optional[CachedImage] = None
+  birthdate: Optional[str] = None
+  books_count: Optional[int] = None
+  created_at: Optional[datetime] = None
+  email: Optional[str] = None
+  followers_count: Optional[int] = None
+  followed_users_count: Optional[int] = None
+  image_id: Optional[int] = None
+  last_activity_at: Optional[datetime] = None
+  last_sign_in_at: Optional[datetime] = None
+  librarian_roles: Optional[List[str]] = None # literal but which values? (appender, editor, librarian)
+  object_type: Optional[Literal['User']] = None
+  username: Optional[str] = None
+  updated_at: Optional[datetime] = None
+
+class UserStatus(BaseModel):
+  id: Optional[int] = None
+  status: Optional[Literal["created", "activated", "banned"]] = None

hardpycover-0.1.0/hardcoverpy/classes/user_stats.py

@@ -0,0 +1,56 @@
+from datetime import datetime, date
+from typing import Optional, Annotated
+from pydantic import BaseModel
+
+class SumAvgStdFields(BaseModel):
+  """
+    List of available fields for use in the `avg` table of the API. 
+  """
+  book_id: Optional[int | float] = None
+  edition_id: Optional[int | float] = None
+  id: Optional[int | float] = None
+  likes_count: Optional[int | float] = None
+  original_book_id: Optional[int | float] = None
+  original_edition_id: Optional[int | float] = None
+  rating: Optional[int | float] = None
+  read_count: Optional[int | float] = None
+  referrer_user_id: Optional[int | float] = None
+  review_length: Optional[int | float] = None
+  user_id: Optional[int | float] = None
+
+class MaxMinFields(BaseModel):
+  """
+    List of available fields for use in the `max/min` table of the API.
+  """
+  book_id: Optional[int | float] = None
+  created_at: Optional[datetime] = None
+  date_added: Optional[date] = None
+  edition_id: Optional[int] = None
+  first_read_date: Optional[date] = None
+  first_started_reading_date: Optional[date] = None
+  id: Optional[int] = None
+  last_read_date: Optional[date] = None
+  likes_count: Optional[int] = None
+  merged_at: Optional[datetime] = None
+  owned_copies: Optional[int] = None
+  rating: Optional[int] = None
+  read_count: Optional[int] = None
+  review: Optional[Annotated[str, "Review text with HTML tags"]] = None
+  review_length: Optional[int] = None
+  review_raw: Optional[Annotated[str, "Review text without HTML tags"]] = None
+  updated_at: Optional[datetime] = None
+  user_id: Optional[int] = None
+
+class AggregateStats(BaseModel):
+  avg: Optional[SumAvgStdFields] = None
+  count: Optional[int] = None
+  max: Optional[MaxMinFields] = None
+  min: Optional[MaxMinFields] = None
+  stddev: Optional[SumAvgStdFields] = None
+  sum: Optional[SumAvgStdFields] = None
+
+  # basic: max, min, stddev
+
+class UserBooksAggregate(BaseModel):
+  aggregate: Optional[AggregateStats] = None
+  # NOTE: nodes support currently on hold

hardpycover-0.1.0/hardcoverpy/classes/userbooks.py

@@ -0,0 +1,42 @@
+from typing import Optional
+from datetime import datetime, date
+from pydantic import BaseModel
+
+from .books import Book
+from .editions import Edition
+
+class UserBook(BaseModel):
+  book_id: Optional[int] = None # matches book id; separate from user_books_id (id)
+  book: Optional[Book] = None
+  created_at: Optional[datetime] = None
+  date_added: Optional[date] = None
+  edition_id: Optional[int] = None
+  edition: Optional[Edition] = None
+  first_read_date: Optional[date] = None
+  first_started_reading_date: Optional[date] = None
+  id: Optional[int] = None
+  has_review: Optional[bool] = None
+  imported: Optional[bool] = None #
+  last_read_date: Optional[date] = None
+  likes_count: Optional[int] = None
+  merged_at: Optional[datetime] = None
+  media_url: Optional[str] = None
+  object_type: Optional['UserBook'] = None
+  original_book_id: Optional[int] = None
+  original_edition_id: Optional[int] = None
+  owned: Optional[bool] = None
+  owned_copies: Optional[int] = None
+  privacy_setting_id: Optional[int] = None
+  read_count: Optional[int] = None
+  reading_format_id: Optional[int] = None
+  recommended_for: Optional[str] = None
+  recommended_by: Optional[str] = None
+  referrer_user_id: Optional[int] = None
+  review: Optional[str] = None
+  review_has_spoilers: Optional[bool] = None
+  rating: Optional[int | float] = None
+  starred: Optional[bool] = None
+  sponsored_review: Optional[bool] = None
+  url: Optional[str] = None
+  updated_at: Optional[datetime] = None
+  user_id: Optional[int] = None

hardpycover-0.1.0/hardcoverpy/classes/utils.py

@@ -0,0 +1,38 @@
+from typing import Optional, List
+from pydantic import BaseModel
+
+class Image(BaseModel):
+    id: int
+    url: str
+    color: str
+    width: int
+    height: int
+    color_name: str
+
+class CachedImage(Image):
+    pass
+
+class LinkType(BaseModel):
+    key: str
+
+class Link(BaseModel):
+    url: str
+    type: LinkType
+    title: str
+
+class Identifiers(BaseModel):
+    goodreads: Optional[List[str]] = None
+    openlibrary: Optional[List[str]] = None
+
+class MatchedTokens(BaseModel):
+    matched_tokens: Optional[List[str]] = None
+    snippet: Optional[str] = None
+
+class TextMatchInfo(BaseModel):
+    best_field_score: Optional[str] = None # String representation of an int value
+    best_field_weight: Optional[int] = None
+    fields_matched: Optional[int] = None
+    num_tokens_dropped: Optional[int] = None
+    score: Optional[str] = None
+    tokens_matched: Optional[int] = None
+    typo_prefix_score: Optional[int] = None

hardpycover-0.1.0/hardcoverpy/core/__init__.py

@@ -0,0 +1,4 @@
+from .base import GraphQLClient
+from .http import HardcoverEndpoint
+
+__all__ = ("GraphQLClient", "HardcoverEndpoint")

hardpycover-0.1.0/hardcoverpy/core/base.py

@@ -0,0 +1,87 @@
+import json
+import urllib
+from urllib.request import urlopen
+from urllib.error import HTTPError
+from typing import Dict, Optional
+from .exceptions import GraphQLError
+
+__all__ = ('GraphQLClient')
+
+class GraphQLClient:
+  """
+  Instantiate a standard GraphQL client.
+
+  Args:
+    endpoint (str): The API endpoint to be used for the request
+    headers (dict): Headers to be passed alongside request
+  """
+
+  def __init__(
+    self, 
+    endpoint: str, 
+    headers: Optional[Dict[str, str]] = None
+  ):
+    self.endpoint = endpoint
+    self.headers = headers or {}
+
+    if 'Content-Type' not in self.headers:
+      self.headers['Content-Type'] = 'application/json'
+
+  def execute(self, query: str):
+    payload = {
+      'query': query
+    }
+
+    data = json.dumps(payload).encode('utf-8')
+
+    try:
+      request = urllib.request.Request(
+        self.endpoint,
+        data=data,
+        headers=self.headers,
+        method='POST'
+      )
+    
+      with urlopen(request) as response:
+        response_data = json.loads(response.read().decode('utf-8'))
+      if 'errors' in response_data:
+        raise GraphQLError(
+          errors=response_data['errors'],
+          data=response_data.get('data')
+        )
+      
+      return response_data.get('data', {}) # default
+    
+    except HTTPError as e:
+      # Return custom exception based on HTTP error code
+      code = e.code
+      # body = e.read().decode('utf-8') if e.fp else 'No error details'
+      if code == 401:
+        print(f"HTTP {code}: Bearer token invalid/expired.")
+        return False
+      if code == 403:
+        print(f"HTTP {code}: User does not have access to requested resource.")
+        return False
+      
+      # raise HTTPError(
+      #   e.url, e.code, f"HTTP {e.code}: {error_body}", e.headers, e.fp
+      # )
+    
+    # TODO: implement cleaner exception handling
+  
+  def set_auth_token(self, token: str, token_type: str = 'Bearer'):
+    """
+    Set authentication token.
+
+    Args:
+      token: The authentication token
+      token_type: The token type (e.g, 'Bearer', 'Token')
+    """
+
+    if 'Bearer' in token:
+      self.headers['Authorization'] = f'{token}'
+    elif 'Bearer' not in token and token_type == 'Bearer':
+      token = token.replace(' ', '')
+      self.headers['Authorization'] = f'Bearer {token}'
+
+### build test cases somewhere?

hardpycover-0.1.0/hardcoverpy/core/exceptions.py

@@ -0,0 +1,20 @@
+'''
+    To be deprecated as exceptions will be bundled within each request.
+'''
+
+from typing import Any
+
+class GraphQLError(Exception):
+    """Custom exception for GraphQL errors"""
+    def __init__(self, errors: list, data: Any = None):
+        self.errors = errors
+        self.data = data
+        super().__init__(f"GraphQL errors: {errors}")
+
+class InvalidTokenError(Exception):
+    def __init__(self):
+        super().__init__("Bearer token invalid/expired.")
+
+class RestrictedAccessError(Exception):
+    def __init__(self):
+        super().__init__("User does not have access to requested resource.")