initial commit

src/wallabag_api_client/__init__.py

@@ -0,0 +1,21 @@
+from .client import WallabagClient
+from .methods.annotations import AnnotationsAPI
+from .methods.entries import EntriesAPI
+from .methods.tags import TagsAPI
+
+
+class WallabagAPI:
+    def __init__(
+        self,
+        client_id,
+        client_secret,
+        username,
+        password,
+        base_url="https://app.wallabag.it",
+    ):
+        self.client = WallabagClient(
+            client_id, client_secret, username, password, base_url
+        )
+        self.entries = EntriesAPI(self.client)
+        self.tags = TagsAPI(self.client)
+        self.annotations = AnnotationsAPI(self.client)

src/wallabag_api_client/client.py

@@ -0,0 +1,124 @@
+import requests
+
+
+class WallabagClient:
+    """
+    A client to interact with the Wallabag API using OAuth2 for authentication.
+
+    This class handles authentication and sending requests to the API endpoints.
+    ----------
+    Attributes
+
+    client_id : str
+        The client ID for OAuth2 authentication.
+    client_secret : str
+        The client secret for OAuth2 authentication.
+    username : str
+        The username of the Wallabag account.
+    password : str
+        The password of the Wallabag account.
+    base_url : str
+        The base URL of the Wallabag instance.
+    token : str
+        The access token obtained from the OAuth2 authentication.
+    """
+
+    def __init__(
+        self,
+        client_id,
+        client_secret,
+        username,
+        password,
+        base_url="https://app.wallabag.it",
+    ):
+        """
+        Initializes the WallabagClient with user credentials and OAuth2 tokens.
+
+        ----------
+        Parameters
+
+        client_id : str
+            The client ID for OAuth2 authentication.
+        client_secret : str
+            The client secret for OAuth2 authentication.
+        username : str
+            The username of the Wallabag account.
+        password : str
+            The password of the Wallabag account.
+        base_url : str, optional
+            The base URL of the Wallabag instance (default is "https://app.wallabag.it").
+        """
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.username = username
+        self.password = password
+        self.base_url = base_url
+        self.token = self.authenticate()
+
+    def authenticate(self):
+        """
+        Authenticates the user and retrieves the access token using OAuth2.
+
+        ----------
+        Returns
+
+        str
+            The access token for making authenticated API requests.
+
+        ----------
+        Raises
+
+        requests.exceptions.HTTPError
+            If the authentication request fails.
+        """
+        auth_url = f"{self.base_url}/oauth/v2/token"
+        data = {
+            "grant_type": "password",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "username": self.username,
+            "password": self.password,
+        }
+        response = requests.post(auth_url, data=data)
+        response.raise_for_status()
+        token_info = response.json()
+        return token_info["access_token"]
+
+    def make_request(self, method, endpoint, params=None, data=None):
+        """
+        Makes a request to the Wallabag API with the given parameters.
+
+        ----------
+        Parameters
+
+        method : str
+            The HTTP method (GET, POST, DELETE, etc.).
+        endpoint : str
+            The API endpoint (e.g., 'entries.json').
+        params : dict, optional
+            The query parameters to include in the request.
+        data : dict, optional
+            The data to send with the request (for POST, PUT, etc.).
+
+        ----------
+        Returns
+
+        dict
+            The response from the API as a dictionary.
+
+        ----------
+        Raises
+
+        requests.exceptions.HTTPError
+            If the request fails.
+        """
+        headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+        url = f"{self.base_url}/api/{endpoint}"
+        response = requests.request(
+            method, url, headers=headers, params=params, json=data
+        )
+        response.raise_for_status()
+        return response.json()

src/wallabag_api_client/methods/annotations.py

@@ -0,0 +1,83 @@
+class AnnotationsAPI:
+    """
+    A class to interact with the Wallabag API for managing annotations on entries.
+
+    ----------
+    Attributes
+
+    client : WallabagClient
+        The client instance to send API requests.
+    """
+
+    def __init__(self, client):
+        """
+        Initializes the AnnotationsAPI with the WallabagClient.
+
+        ----------
+        Parameters
+
+        client : WallabagClient
+            The WallabagClient instance to send requests.
+        """
+        self.client = client
+
+    def get_annotations(self, entry_id):
+        """
+        Retrieves all annotations for a specific entry.
+
+        ----------
+        Parameters
+
+        entry_id : int
+            The ID of the entry for which to retrieve annotations.
+
+        ----------
+        Returns
+
+        dict
+            The list of annotations for the specified entry.
+        """
+        return self.client.make_request("GET", f"annotations/{entry_id}.json")
+
+    def add_annotation(self, entry_id, text, quote):
+        """
+        Adds a new annotation to a specific entry.
+
+        ----------
+        Parameters
+
+        entry_id : int
+            The ID of the entry to annotate.
+        text : str
+            The text of the annotation.
+        quote : str
+            The quote related to the annotation.
+
+        ----------
+        Returns
+
+        dict
+            The details of the newly added annotation.
+        """
+        data = {"text": text, "quote": quote}
+        return self.client.make_request(
+            "POST", f"annotations/{entry_id}.json", data=data
+        )
+
+    def delete_annotation(self, annotation_id):
+        """
+        Deletes an annotation from a specific entry.
+
+        ----------
+        Parameters
+
+        annotation_id : int
+            The ID of the annotation to delete.
+
+        ----------
+        Returns
+
+        dict
+            The response from the API after deleting the annotation.
+        """
+        return self.client.make_request("DELETE", f"annotations/{annotation_id}.json")

src/wallabag_api_client/methods/entries.py

@@ -0,0 +1,98 @@
+class EntriesAPI:
+    """
+    A class to interact with the Wallabag API for managing entries (articles).
+
+    ----------
+    Attributes
+
+    client : WallabagClient
+        The client instance to send API requests.
+    """
+
+    def __init__(self, client):
+        """
+        Initializes the EntriesAPI with the WallabagClient.
+
+        ----------
+        Parameters
+
+        client : WallabagClient
+            The WallabagClient instance to send requests.
+        """
+        self.client = client
+
+    def get_entries(self, page=1, per_page=30):
+        """
+        Retrieves a paginated list of entries (articles).
+
+        ----------
+        Parameters
+
+        page : int, optional
+            The page number to retrieve (default is 1).
+        per_page : int, optional
+            The number of entries per page (default is 30).
+
+        ----------
+        Returns
+
+        dict
+            The list of entries and pagination info.
+        """
+        params = {"page": page, "perPage": per_page}
+        return self.client.make_request("GET", "entries.json", params=params)
+
+    def add_entry(self, url):
+        """
+        Adds a new entry to Wallabag by providing a URL.
+
+        ----------
+        Parameters
+        ----------
+        url : str
+            The URL of the article to add.
+
+        ----------
+        Returns
+
+        dict
+            The details of the newly added entry.
+        """
+        data = {"url": url}
+        return self.client.make_request("POST", "entries.json", data=data)
+
+    def delete_entry(self, entry_id):
+        """
+        Deletes an entry from Wallabag by its entry ID.
+
+        ----------
+        Parameters
+
+        entry_id : int
+            The ID of the entry to delete.
+
+        ----------
+        Returns
+
+        dict
+            The response from the API after deleting the entry.
+        """
+        return self.client.make_request("DELETE", f"entries/{entry_id}.json")
+
+    def get_entry(self, entry_id):
+        """
+        Retrieves the details of a specific entry by its ID.
+
+        ----------
+        Parameters
+
+        entry_id : int
+            The ID of the entry to retrieve.
+
+        ----------
+        Returns
+
+        dict
+            The details of the specified entry.
+        """
+        return self.client.make_request("GET", f"entries/{entry_id}.json")

src/wallabag_api_client/methods/tags.py

@@ -0,0 +1,73 @@
+class TagsAPI:
+    """
+    A class to interact with the Wallabag API for managing tags.
+
+    ----------
+    Attributes
+
+    client : WallabagClient
+        The client instance to send API requests.
+    """
+
+    def __init__(self, client):
+        """
+        Initializes the TagsAPI with the WallabagClient.
+
+        ----------
+        Parameters
+
+        client : WallabagClient
+            The WallabagClient instance to send requests.
+        """
+        self.client = client
+
+    def get_tags(self):
+        """
+        Retrieves all tags associated with entries in Wallabag.
+
+        ----------
+        Returns
+
+        dict
+            The list of tags.
+        """
+        return self.client.make_request("GET", "tags.json")
+
+    def add_tag(self, entry_id, tag):
+        """
+        Adds a tag to a specific entry.
+
+        ----------
+        Parameters
+
+        entry_id : int
+            The ID of the entry to tag.
+        tag : str
+            The tag to add to the entry.
+
+        ----------
+        Returns
+
+        dict
+            The response from the API after adding the tag.
+        """
+        data = {"entry_id": entry_id, "label": tag}
+        return self.client.make_request("POST", "tags.json", data=data)
+
+    def delete_tag(self, tag_id):
+        """
+        Deletes a tag from an entry.
+
+        ----------
+        Parameters
+
+        tag_id : int
+            The ID of the tag to delete.
+
+        ----------
+        Returns
+
+        dict
+            The response from the API after deleting the tag.
+        """
+        return self.client.make_request("DELETE", f"tags/{tag_id}.json")