taskbadger 0.1__tar.gz → 0.2.1__tar.gz

{taskbadger-0.1 → taskbadger-0.2.1}/PKG-INFO

@@ -1,22 +1,42 @@
 Metadata-Version: 2.1
 Name: taskbadger
-Version: 0.1
+Version: 0.2.1
 Summary: The official Python SDK for Task Badger
+Home-page: https://taskbadger.net/
+License: Apache-2.0
 Requires-Python: >=3.8,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: attrs (>=21.3.0)
 Requires-Dist: httpx (>=0.15.4,<0.24.0)
 Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
 Requires-Dist: tomlkit (>=0.11.6,<0.12.0)
 Requires-Dist: typer[all] (>=0.7.0,<0.8.0)
+Project-URL: Documentation, https://docs.taskbadger.net/
+Project-URL: Repository, https://github.com/taskbadger/taskbadger-docs
 Description-Content-Type: text/markdown
 
 # Task Badger Python Client
-This is the official Python SDK for [Task Badger](https://taskbadger.net/)
+
+This is the official Python SDK for [Task Badger](https://taskbadger.net/).
+
+For full documentation go to https://docs.taskbadger.net/python/.
 
 ---
 
@@ -59,12 +79,12 @@ task = Task.create(
     ]
 )
 
-# update the task status to 'processing'
-task.start()
+# update the task status to 'processing' and set the value to 0
+task.started()
 try:
    for i in range(100):
       do_something(i)
-      if i % 10 == 0:
+      if i!= 0 and i % 10 == 0:
          # update the progress of the task
          task.update_progress(i)
 except Exception as e:

{taskbadger-0.1 → taskbadger-0.2.1}/README.md

@@ -1,5 +1,8 @@
 # Task Badger Python Client
-This is the official Python SDK for [Task Badger](https://taskbadger.net/)
+
+This is the official Python SDK for [Task Badger](https://taskbadger.net/).
+
+For full documentation go to https://docs.taskbadger.net/python/.
 
 ---
 
@@ -42,12 +45,12 @@ task = Task.create(
     ]
 )
 
-# update the task status to 'processing'
-task.start()
+# update the task status to 'processing' and set the value to 0
+task.started()
 try:
    for i in range(100):
       do_something(i)
-      if i % 10 == 0:
+      if i!= 0 and i % 10 == 0:
          # update the progress of the task
          task.update_progress(i)
 except Exception as e:

{taskbadger-0.1 → taskbadger-0.2.1}/pyproject.toml

@@ -1,7 +1,8 @@
 [tool.poetry]
 name = "taskbadger"
-version = "0.1"
+version = "0.2.1"
 description = "The official Python SDK for Task Badger"
+license = "Apache-2.0"
 
 authors = []
 
@@ -11,6 +12,24 @@ packages = [
 ]
 include = ["CHANGELOG.md", "taskbadger/internal/py.typed"]
 
+homepage = "https://taskbadger.net/"
+repository = "https://github.com/taskbadger/taskbadger-docs"
+documentation = "https://docs.taskbadger.net/"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
 [tool.poetry.dependencies]
 python = "^3.8"
 httpx = ">=0.15.4,<0.24.0"
@@ -25,6 +44,7 @@ pytest = "^7.2.1"
 isort = "^5.12.0"
 black = "^23.1.0"
 pre-commit = "^3.0.2"
+pytest-httpx = "^0.21.3"
 
 [tool.poetry.scripts]
 taskbadger = "taskbadger.cli:app"

taskbadger-0.2.1/setup.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+from setuptools import setup
+
+packages = \
+['taskbadger',
+ 'taskbadger.internal',
+ 'taskbadger.internal.api',
+ 'taskbadger.internal.api.action_endpoints',
+ 'taskbadger.internal.api.task_endpoints',
+ 'taskbadger.internal.models']
+
+package_data = \
+{'': ['*']}
+
+install_requires = \
+['attrs>=21.3.0',
+ 'httpx>=0.15.4,<0.24.0',
+ 'python-dateutil>=2.8.0,<3.0.0',
+ 'tomlkit>=0.11.6,<0.12.0',
+ 'typer[all]>=0.7.0,<0.8.0']
+
+entry_points = \
+{'console_scripts': ['taskbadger = taskbadger.cli:app']}
+
+setup_kwargs = {
+    'name': 'taskbadger',
+    'version': '0.2.1',
+    'description': 'The official Python SDK for Task Badger',
+    'long_description': '# Task Badger Python Client\n\nThis is the official Python SDK for [Task Badger](https://taskbadger.net/).\n\nFor full documentation go to https://docs.taskbadger.net/python/.\n\n---\n\n## Getting Started\n\n### Install\n\n```bash\npip install --upgrade taskbadger\n```\n\n### Configuration\n\n```python\nimport taskbadger\n\ntaskbadger.init(\n    organization_slug="my-org",\n    project_slug="my-project",\n    token="***"\n)\n```\n\n### Usage\n\n```python\nfrom taskbadger import Task, Action, EmailIntegration\n\n# create a new task with custom data and an action definition\ntask = Task.create(\n    "task name",\n    data={\n        "custom": "data"\n    },\n    actions=[\n        Action(\n            "*/10%,success,error",\n            integration=EmailIntegration(to="me@example.com")\n        )\n    ]\n)\n\n# update the task status to \'processing\' and set the value to 0\ntask.started()\ntry:\n   for i in range(100):\n      do_something(i)\n      if i!= 0 and i % 10 == 0:\n         # update the progress of the task\n         task.update_progress(i)\nexcept Exception as e:\n    # record task errors\n    task.error(data={\n        "error": str(e)\n    })\n    raise\n\n# record task success\ntask.success()\n```\n',
+    'author': 'None',
+    'author_email': 'None',
+    'maintainer': 'None',
+    'maintainer_email': 'None',
+    'url': 'https://taskbadger.net/',
+    'packages': packages,
+    'package_data': package_data,
+    'install_requires': install_requires,
+    'entry_points': entry_points,
+    'python_requires': '>=3.8,<4.0',
+}
+
+
+setup(**setup_kwargs)

taskbadger-0.2.1/taskbadger/__init__.py

@@ -0,0 +1,3 @@
+from .integrations import Action, EmailIntegration
+from .sdk import Task, init, get_task, create_task, update_task
+from .internal.models import StatusEnum

taskbadger-0.2.1/taskbadger/internal/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

{taskbadger-0.1 → taskbadger-0.2.1}/taskbadger/sdk.py

@@ -1,22 +1,24 @@
 import dataclasses
 import os
-from typing import List
-
 from _contextvars import ContextVar
+from typing import List
 
 from taskbadger import Action
 from taskbadger.exceptions import ConfigurationError
 from taskbadger.internal import AuthenticatedClient, errors
 from taskbadger.internal.api.task_endpoints import task_create, task_get, task_partial_update
-from taskbadger.internal.models import PatchedTaskRequest, PatchedTaskRequestData, StatusEnum
-from taskbadger.internal.models import Task as CoreTask
-from taskbadger.internal.models import TaskData, TaskRequest
+from taskbadger.internal.models import PatchedTaskRequest, PatchedTaskRequestData, StatusEnum, TaskRequestData
+from taskbadger.internal.models import TaskRequest
 from taskbadger.internal.types import UNSET
 
 _local = ContextVar("taskbadger_client")
 
 
 def init(organization_slug: str = None, project_slug: str = None, token: str = None):
+    """Initialize Task Badger client
+
+    Call this function once per thread
+    """
     _init("https://taskbadger.net", organization_slug, project_slug, token)
 
 
@@ -39,46 +41,89 @@ def _init(host: str = None, organization_slug: str = None, project_slug: str = N
         )
 
 
-def get_task(task_id: str):
-    return task_get.sync(**_make_args(id=task_id))
+def get_task(task_id: str) -> "Task":
+    """Fetch a Task from the API based on its ID.
+
+    Arguments:
+        task_id: The ID of the task to fetch.
+    """
+    return Task(task_get.sync(**_make_args(id=task_id)))
 
 
 def create_task(
     name: str,
     status: StatusEnum = StatusEnum.PENDING,
-    value: int = UNSET,
-    value_max: int = UNSET,
-    data: dict = UNSET,
+    value: int = None,
+    value_max: int = None,
+    data: dict = None,
     actions: List[Action] = None,
-) -> CoreTask:
+) -> "Task":
+    """Create a Task.
+
+    Arguments:
+        name: The name of the task.
+        status: The task status.
+        value: The current 'value' of the task.
+        value_max: The maximum value the task is expected to achieve.
+        data: Custom task data.
+        actions: Task actions.
+
+    Returns:
+        Task: The created Task object.
+    """
+    value = _none_to_unset(value)
+    value_max = _none_to_unset(value_max)
+    data = _none_to_unset(data)
+
     task = TaskRequest(name=name, status=status, value=value, value_max=value_max)
     if data:
-        task.data = TaskData.from_dict(data)
+        task.data = TaskRequestData.from_dict(data)
     if actions:
         task.additional_properties = {"actions": [a.to_dict() for a in actions]}
     kwargs = _make_args(json_body=task)
     response = task_create.sync_detailed(**kwargs)
     _check_response(response)
-    return response.parsed
+    return Task(response.parsed)
 
 
 def update_task(
     task_id: str,
-    name: str = UNSET,
-    status: StatusEnum = UNSET,
-    value: int = UNSET,
-    value_max: int = UNSET,
-    data: dict = UNSET,
+    name: str = None,
+    status: StatusEnum = None,
+    value: int = None,
+    value_max: int = None,
+    data: dict = None,
     actions: List[Action] = None,
-) -> CoreTask:
-    data = UNSET if data is UNSET else PatchedTaskRequestData.from_dict(data)
+) -> "Task":
+    """Update a task.
+    Requires only the task ID and fields to update.
+
+    Arguments:
+        task_id: The ID of the task to update.
+        name: The name of the task.
+        status: The task status.
+        value: The current 'value' of the task.
+        value_max: The maximum value the task is expected to achieve.
+        data: Custom task data.
+        actions: Task actions.
+
+    Returns:
+        Task: The updated Task object.
+    """
+    name = _none_to_unset(name)
+    status = _none_to_unset(status)
+    value = _none_to_unset(value)
+    value_max = _none_to_unset(value_max)
+    data = _none_to_unset(data)
+
+    data = UNSET if not data else PatchedTaskRequestData.from_dict(data)
     body = PatchedTaskRequest(name=name, status=status, value=value, value_max=value_max, data=data)
     if actions:
         body.additional_properties = {"actions": [a.to_dict() for a in actions]}
     kwargs = _make_args(id=task_id, json_body=body)
     response = task_partial_update.sync_detailed(**kwargs)
     _check_response(response)
-    return response.parsed
+    return Task(response.parsed)
 
 
 def _make_args(**kwargs):
@@ -107,75 +152,101 @@ class Settings:
     project_slug: str
 
 
-class TaskAccessorsMixin:
+class Task:
+    """The Task class provides a convenient Python API to interact
+    with Task Badger tasks.
+    """
+
     @classmethod
     def get(cls, task_id: str) -> "Task":
-        return Task(get_task(task_id))
+        """Get an existing task"""
+        return get_task(task_id)
 
     @classmethod
     def create(
-        cls,
-        name: str,
-        status: StatusEnum = StatusEnum.PENDING,
-        value: int = UNSET,
-        value_max: int = UNSET,
-        data: dict = UNSET,
-        actions: List[Action] = None,
+            cls,
+            name: str,
+            status: StatusEnum = StatusEnum.PENDING,
+            value: int = None,
+            value_max: int = None,
+            data: dict = None,
+            actions: List[Action] = None,
     ) -> "Task":
-        return Task(create_task(name, status, value, value_max, data, actions))
-
+        """Create a new task"""
+        return create_task(name, status, value, value_max, data, actions)
 
-class Task(TaskAccessorsMixin):
     def __init__(self, task):
         self._task = task
 
     def pre_processing(self):
+        """Update the task status to `pre_processing`."""
         self.update_status(StatusEnum.PRE_PROCESSING)
 
-    def start(self):
+    def starting(self):
+        """Update the task status to `pre_processing` and set the value to `0`."""
         self.processing(value=0)
 
-    def processing(self, value: int = UNSET):
+    def processing(self, value: int = None):
+        """Update the task status to `processing` and set the value."""
         self.update(status=StatusEnum.PROCESSING, value=value)
 
-    def post_processing(self, value: int = UNSET):
+    def post_processing(self, value: int = None):
+        """Update the task status to `post_processing` and set the value."""
         self.update(status=StatusEnum.POST_PROCESSING, value=value)
 
-    def success(self, value: int = UNSET):
+    def success(self, value: int = None):
+        """Update the task status to `success` and set the value."""
         self.update(status=StatusEnum.SUCCESS, value=value)
 
-    def error(self, value: int = UNSET, data: dict = UNSET):
+    def error(self, value: int = None, data: dict = None):
+        """Update the task status to `error` and set the value and data."""
         self.update(status=StatusEnum.ERROR, value=value, data=data)
 
-    def cancel(self):
+    def canceled(self):
+        """Update the task status to `cancelled`"""
         self.update_status(StatusEnum.CANCELLED)
 
     def update_status(self, status: StatusEnum):
+        """Update the task status"""
         self.update(status=status)
 
     def increment_progress(self, amount: int):
-        self.update(value=self._task.value + amount)
+        """Increment the task progress.
+        If the task value is not set it will be set to `amount`.
+        """
+        value = self._task.value
+        value_norm = value if value is not UNSET and value is not None else 0
+        new_amount = value_norm + amount
+        self.update(value=new_amount)
 
     def update_progress(self, value: int):
+        """Update task progress."""
         self.update(value=value)
 
     def set_value_max(self, value_max: int):
+        """Set the `value_max`."""
         self.update(value_max=value_max)
 
     def update(
         self,
-        name: str = UNSET,
-        status: StatusEnum = UNSET,
-        value: int = UNSET,
-        value_max: int = UNSET,
-        data: dict = UNSET,
+        name: str = None,
+        status: StatusEnum = None,
+        value: int = None,
+        value_max: int = None,
+        data: dict = None,
         actions: List[Action] = None,
     ):
-        self._task = update_task(
+        """Generic update method used to update any of the task fields.
+
+        This can also be used to add actions.
+        """
+        task = update_task(
             self._task.id, name=name, status=status, value=value, value_max=value_max, data=data, actions=actions
         )
+        self._task = task._task
 
     def add_actions(self, actions: List[Action]):
+        """Add actions to the task."""
         self.update(actions=actions)
 
     @property
@@ -184,3 +255,7 @@ class Task(TaskAccessorsMixin):
 
     def __getattr__(self, item):
         return getattr(self._task, item)
+
+
+def _none_to_unset(value):
+    return UNSET if value is None else value

taskbadger-0.1/setup.py

@@ -1,43 +0,0 @@
-# -*- coding: utf-8 -*-
-from setuptools import setup
-
-packages = \
-['taskbadger',
- 'taskbadger.internal',
- 'taskbadger.internal.api',
- 'taskbadger.internal.api.action_endpoints',
- 'taskbadger.internal.api.task_endpoints',
- 'taskbadger.internal.models']
-
-package_data = \
-{'': ['*']}
-
-install_requires = \
-['attrs>=21.3.0',
- 'httpx>=0.15.4,<0.24.0',
- 'python-dateutil>=2.8.0,<3.0.0',
- 'tomlkit>=0.11.6,<0.12.0',
- 'typer[all]>=0.7.0,<0.8.0']
-
-entry_points = \
-{'console_scripts': ['taskbadger = taskbadger.cli:app']}
-
-setup_kwargs = {
-    'name': 'taskbadger',
-    'version': '0.1',
-    'description': 'The official Python SDK for Task Badger',
-    'long_description': '# Task Badger Python Client\nThis is the official Python SDK for [Task Badger](https://taskbadger.net/)\n\n---\n\n## Getting Started\n\n### Install\n\n```bash\npip install --upgrade taskbadger\n```\n\n### Configuration\n\n```python\nimport taskbadger\n\ntaskbadger.init(\n    organization_slug="my-org",\n    project_slug="my-project",\n    token="***"\n)\n```\n\n### Usage\n\n```python\nfrom taskbadger import Task, Action, EmailIntegration\n\n# create a new task with custom data and an action definition\ntask = Task.create(\n    "task name",\n    data={\n        "custom": "data"\n    },\n    actions=[\n        Action(\n            "*/10%,success,error",\n            integration=EmailIntegration(to="me@example.com")\n        )\n    ]\n)\n\n# update the task status to \'processing\'\ntask.start()\ntry:\n   for i in range(100):\n      do_something(i)\n      if i % 10 == 0:\n         # update the progress of the task\n         task.update_progress(i)\nexcept Exception as e:\n    # record task errors\n    task.error(data={\n        "error": str(e)\n    })\n    raise\n\n# record task success\ntask.success()\n```\n',
-    'author': 'None',
-    'author_email': 'None',
-    'maintainer': 'None',
-    'maintainer_email': 'None',
-    'url': 'None',
-    'packages': packages,
-    'package_data': package_data,
-    'install_requires': install_requires,
-    'entry_points': entry_points,
-    'python_requires': '>=3.8,<4.0',
-}
-
-
-setup(**setup_kwargs)

taskbadger-0.1/taskbadger/__init__.py

@@ -1,2 +0,0 @@
-from .integrations import Action, EmailIntegration
-from .sdk import Task, init, update_task

taskbadger-0.1/taskbadger/internal/py.typed

@@ -1 +0,0 @@
-# Marker file for PEP 561