python-jira-plus 3.2.0__tar.gz → 4.1.0__tar.gz

{python_jira_plus-3.2.0/python_jira_plus.egg-info → python_jira_plus-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-jira-plus
-Version: 3.2.0
+Version: 4.1.0
 Summary: Enhanced Python client for JIRA with better error handling, pagination, and metadata validation.
 Author: Avi Zaguri
 License: MIT
@@ -21,11 +21,6 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: jira>=3.10.5
 Requires-Dist: packaging>=26.2
 Requires-Dist: requests>=2.32.5
-Provides-Extra: dev
-Requires-Dist: pre-commit>=4.5.0; extra == "dev"
-Requires-Dist: pytest>=9.0.1; extra == "dev"
-Requires-Dist: setuptools>=80.9.0; extra == "dev"
-Requires-Dist: wheel>=0.45.1; extra == "dev"
 Dynamic: license-file
 
 ![PyPI version](https://img.shields.io/pypi/v/python-jira-plus)
@@ -44,7 +39,7 @@ An enhanced Python client for JIRA that extends the functionality of the officia
 
 ## Features
 - ✅ Simplified connection to JIRA Cloud and On-Premise instances
-- ✅ Robust error handling with automatic retries
+- ✅ Clear error handling: failures raise (`raise_on_error=True`) or are logged and returned as `None`/`False`. Rate limits (429) and 503 are retried by `jira-python` itself
 - ✅ Built-in pagination for large result sets
 - ✅ Field validation against JIRA metadata
 - ✅ Enhanced issue creation, retrieval, and updating
@@ -62,7 +57,6 @@ pip install python-jira-plus
 ## Requirements
 - Python 3.12+
 - `jira` package
-- `retrying` package
 - `custom-python-logger` package
 
 ---
@@ -77,13 +71,26 @@ JIRA_TOKEN=your_jira_api_token
 JIRA_BASE_URL=your-instance.atlassian.net  # Only used if base_url is not provided to constructor
 ```
 
+## Error handling
+By default, write helpers (`delete_issue`, `create_link`, `transition_issue`, `upload_attachment`,
+`update_issue`) and `get_issue_by_key` log the error and return `False`/`None`. Pass
+`raise_on_error=True` to the constructor to get the original exception instead:
+
+```python
+jira_client = JiraCloud(raise_on_error=True)
+jira_client.get_issue_by_key("PROJ-404")  # raises JIRAError instead of returning None
+```
+
+Validation problems (`ValueError`) and failed searches (`JIRAError`) are always raised.
+Rate limits (429) and 503 are retried by `jira-python`'s own session, not by this package.
+
 ## Examples
 
 ### Creating an Issue with Custom Fields
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud  # or JiraOnPremise
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issue = jira_client.create_issue(
     project_key="PROJ",
     summary="Implement new feature",
@@ -98,12 +105,13 @@ issue = jira_client.create_issue(
 
 ### Searching for Issues
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issues = jira_client.get_objects_by_query(
     query="project = PROJ AND status = 'In Progress' ORDER BY created DESC",
-    max_results=50,
+    max_results=50,  # page size
+    limit=200,  # optional cap on the total number of issues returned
     specific_fields=["summary", "status", "assignee"],
     json_result=False
 )
@@ -114,9 +122,9 @@ for issue in issues:
 
 ### Updating an Issue
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issue = jira_client.get_issue_by_key(key="PROJ-123", json_result=False)
 
 fields_to_update = {

{python_jira_plus-3.2.0 → python_jira_plus-4.1.0}/README.md

@@ -14,7 +14,7 @@ An enhanced Python client for JIRA that extends the functionality of the officia
 
 ## Features
 - ✅ Simplified connection to JIRA Cloud and On-Premise instances
-- ✅ Robust error handling with automatic retries
+- ✅ Clear error handling: failures raise (`raise_on_error=True`) or are logged and returned as `None`/`False`. Rate limits (429) and 503 are retried by `jira-python` itself
 - ✅ Built-in pagination for large result sets
 - ✅ Field validation against JIRA metadata
 - ✅ Enhanced issue creation, retrieval, and updating
@@ -32,7 +32,6 @@ pip install python-jira-plus
 ## Requirements
 - Python 3.12+
 - `jira` package
-- `retrying` package
 - `custom-python-logger` package
 
 ---
@@ -47,13 +46,26 @@ JIRA_TOKEN=your_jira_api_token
 JIRA_BASE_URL=your-instance.atlassian.net  # Only used if base_url is not provided to constructor
 ```
 
+## Error handling
+By default, write helpers (`delete_issue`, `create_link`, `transition_issue`, `upload_attachment`,
+`update_issue`) and `get_issue_by_key` log the error and return `False`/`None`. Pass
+`raise_on_error=True` to the constructor to get the original exception instead:
+
+```python
+jira_client = JiraCloud(raise_on_error=True)
+jira_client.get_issue_by_key("PROJ-404")  # raises JIRAError instead of returning None
+```
+
+Validation problems (`ValueError`) and failed searches (`JIRAError`) are always raised.
+Rate limits (429) and 503 are retried by `jira-python`'s own session, not by this package.
+
 ## Examples
 
 ### Creating an Issue with Custom Fields
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud  # or JiraOnPremise
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issue = jira_client.create_issue(
     project_key="PROJ",
     summary="Implement new feature",
@@ -68,12 +80,13 @@ issue = jira_client.create_issue(
 
 ### Searching for Issues
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issues = jira_client.get_objects_by_query(
     query="project = PROJ AND status = 'In Progress' ORDER BY created DESC",
-    max_results=50,
+    max_results=50,  # page size
+    limit=200,  # optional cap on the total number of issues returned
     specific_fields=["summary", "status", "assignee"],
     json_result=False
 )
@@ -84,9 +97,9 @@ for issue in issues:
 
 ### Updating an Issue
 ```python
-from python_jira_plus.jira_plus import JiraPlus
+from python_jira_plus import JiraCloud
 
-jira_client = JiraPlus()
+jira_client = JiraCloud()
 issue = jira_client.get_issue_by_key(key="PROJ-123", json_result=False)
 
 fields_to_update = {

{python_jira_plus-3.2.0 → python_jira_plus-4.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-jira-plus"
-version = "3.2.0"
+version = "4.1.0"
 description = "Enhanced Python client for JIRA with better error handling, pagination, and metadata validation."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,9 +28,10 @@ dependencies = [
     "requests>=2.32.5",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
     "pre-commit>=4.5.0",
+    "python-base-toolkit>=1.1.2",
     "pytest>=9.0.1",
     "setuptools>=80.9.0",
     "wheel>=0.45.1",

{python_jira_plus-3.2.0 → python_jira_plus-4.1.0}/python_jira_plus/__init__.py

@@ -5,14 +5,11 @@ An enhanced Python client for JIRA with better error handling,
 pagination, metadata validation, and more.
 """
 
-from dotenv import load_dotenv
-
 from python_jira_plus.describe_allowed_value import describe_allowed_value
 from python_jira_plus.jira_base import JiraBase, UrlScheme
 from python_jira_plus.jira_cloud import JiraCloud
 from python_jira_plus.jira_on_premise import JiraOnPremise
-
-load_dotenv()
+from python_jira_plus.types import CreateField
 
 BASIC_FIELDS = [
     "created",
@@ -29,4 +26,12 @@ BASIC_FIELDS = [
     "resolution",
     "parent",
 ]
-__all__ = ["JiraBase", "JiraCloud", "JiraOnPremise", "UrlScheme", "BASIC_FIELDS"]
+__all__ = [
+    "JiraBase",
+    "JiraCloud",
+    "JiraOnPremise",
+    "UrlScheme",
+    "BASIC_FIELDS",
+    "describe_allowed_value",
+    "CreateField",
+]

python_jira_plus-4.1.0/python_jira_plus/consts.py

@@ -0,0 +1,22 @@
+import re
+from typing import NamedTuple
+
+LOGGER_NAME = "python_jira_plus"
+
+
+class FieldTypeCheck(NamedTuple):
+    python_types: type | tuple[type, ...]
+    label: str
+
+
+ALLOWED_VALUE_KEYS = ("name", "key", "value", "id")
+SCHEME_PATTERN = re.compile(r"^(https?)://", re.IGNORECASE)
+FIELD_TYPE_CHECKS = {
+    "string": FieldTypeCheck(str, "a string"),
+    "number": FieldTypeCheck((int, float), "a number"),
+    "boolean": FieldTypeCheck(bool, "a boolean"),
+    "array": FieldTypeCheck(list, "an array"),
+    "object": FieldTypeCheck(dict, "an object"),
+    "issuetype": FieldTypeCheck(dict, "an issue type"),
+}
+ISSUE_REF_PATTERN = re.compile(r"[A-Za-z0-9_]+(-[0-9]+)?")

python_jira_plus-4.1.0/python_jira_plus/helpers.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+from python_jira_plus.consts import ISSUE_REF_PATTERN
+
+
+def allowed_value_label(value: Any) -> str:
+    """A readable label for one entry of a field's `allowedValues`."""
+    if isinstance(value, dict):
+        return str(value.get("name") or value.get("value") or value.get("key") or value.get("id"))
+    return str(value)
+
+
+def check_issue_ref(issue_ref: Any) -> None:
+    """Reject an issue key/id that could change the request path (jira-python does not escape it)."""
+    if isinstance(issue_ref, str) and not ISSUE_REF_PATTERN.fullmatch(issue_ref):
+        raise ValueError(f"Invalid issue key '{issue_ref}'. Expected a key like PROJ-123 or a numeric id")