python-jira-plus 3.2.0__py3-none-any.whl → 4.1.0__py3-none-any.whl

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/consts.py

@@ -1 +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/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")

python_jira_plus/jira_base.py

@@ -8,11 +8,19 @@ from enum import Enum
 from typing import Any
 
 from custom_python_logger import get_logger
+from dotenv import load_dotenv
 from jira import JIRA, Issue, JIRAError
 from jira.client import ResultList
 
-from python_jira_plus.consts import LOGGER_NAME
+from python_jira_plus.consts import (
+    ALLOWED_VALUE_KEYS,
+    FIELD_TYPE_CHECKS,
+    LOGGER_NAME,
+    SCHEME_PATTERN,
+)
 from python_jira_plus.describe_allowed_value import describe_allowed_value
+from python_jira_plus.helpers import allowed_value_label, check_issue_ref
+from python_jira_plus.types import CreateField
 
 
 class UrlScheme(Enum):
@@ -20,7 +28,7 @@ class UrlScheme(Enum):
     HTTPS = "https"
 
 
-class JiraBase(ABC):
+class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
     use_createmeta: bool
 
     def __init__(
@@ -31,21 +39,45 @@ class JiraBase(ABC):
         jira_token: str | None = None,
         verify_ssl: bool = True,
         url_scheme: UrlScheme = UrlScheme.HTTPS,
+        raise_on_error: bool = False,
     ) -> None:
         self.logger = get_logger(LOGGER_NAME)
         get_logger("urllib3").setLevel(urllib3_log_level)
 
+        if not (jira_username and jira_token and base_url):
+            load_dotenv()  # fallback for missing arguments only — no import-time side effect
         self.jira_username = jira_username or os.getenv("JIRA_USER_NAME")
         self.jira_token = jira_token or os.getenv("JIRA_TOKEN")
-        self.base_url = base_url or os.getenv("JIRA_BASE_URL")
-        self.url_scheme = url_scheme.value
+        self.base_url, self.url_scheme = self._parse_base_url(base_url or os.getenv("JIRA_BASE_URL"), url_scheme)
         self.server = f"{self.url_scheme}://{self.base_url}"
         self.verify_ssl = verify_ssl
+        self.raise_on_error = raise_on_error
+        self._validate_credentials()
 
         self.jira_client = self.create_connection()
-        self.check_client_connection()
         self.server_version = self.get_server_version()
 
+    @staticmethod
+    def _parse_base_url(base_url: str | None, url_scheme: UrlScheme) -> tuple[str, str]:
+        """Split an optional scheme off `base_url`; a scheme embedded in the URL wins over `url_scheme`."""
+        if not base_url or not base_url.strip():
+            raise ValueError("Jira base URL is missing — pass `base_url` or set JIRA_BASE_URL")
+        base_url = base_url.strip()
+        scheme = url_scheme.value
+        if match := SCHEME_PATTERN.match(base_url):
+            scheme = match.group(1).lower()
+            base_url = base_url[match.end() :]
+        return base_url.rstrip("/"), scheme
+
+    def _requires_username(self) -> bool:
+        return True
+
+    def _validate_credentials(self) -> None:
+        if not self.jira_token:
+            raise ValueError("Jira token is missing — pass `jira_token` or set JIRA_TOKEN")
+        if self._requires_username() and not self.jira_username:
+            raise ValueError("Jira username is missing — pass `jira_username` or set JIRA_USER_NAME")
+
     @abstractmethod
     def create_connection(self, timeout: int = 580) -> JIRA: ...
 
@@ -55,13 +87,19 @@ class JiraBase(ABC):
         query: str,
         max_results: int,
         specific_fields: str | list[str],
-        jira_err_limit: int,
         json_result: bool,
+        limit: int | None = None,
     ) -> ResultList[Issue] | list: ...
 
     @abstractmethod
     def _format_assignee(self, assignee: str) -> dict: ...
 
+    def _handle_error(self, message: str, err: Exception) -> None:
+        """Log `err`; re-raise it when `raise_on_error` is set. Callers return their failure value after."""
+        self.logger.exception(f"{message}\n{err}")
+        if self.raise_on_error:
+            raise err
+
     def close_connection(self) -> None:
         try:
             self.jira_client.close()
@@ -69,7 +107,6 @@ class JiraBase(ABC):
             self.logger.exception(f"JIRAError \n{err}")
         except Exception as err:
             self.logger.exception(f"Exception \n{err}")
-        self.check_client_connection()
 
     def check_client_connection(self) -> bool:
         try:
@@ -90,16 +127,14 @@ class JiraBase(ABC):
     def get_issue_by_key(
         self, key: str, specific_fields: str | list[str] = "*all", json_result: bool = True
     ) -> None | Issue | dict[str, Any]:
+        check_issue_ref(key)
         try:
             jira_issue = self.jira_client.issue(id=key, fields=specific_fields)
             if json_result:
                 return jira_issue.raw
             return jira_issue
-        except JIRAError as err:
-            self.logger.exception(f"JIRAError \n{err}")
-            return None
         except Exception as err:
-            self.logger.exception(f"Exception \n{err}")
+            self._handle_error(f"Failed to get issue {key}", err)
             return None
 
     def get_objects_by_query(
@@ -107,31 +142,58 @@ class JiraBase(ABC):
         query: str,
         max_results: int = 5000,
         specific_fields: str | list[str] = "*all",
-        jira_err_count: int = 3,
         json_result: bool = True,
+        limit: int | None = None,
     ) -> ResultList[Issue] | list:
+        """Run a JQL query and return all matches.
+
+        Args:
+            query: JQL string.
+            max_results: Page size (on-premise: also the total cap unless `limit` is given).
+            specific_fields: Fields to fetch.
+            json_result: Return raw dicts instead of `Issue` objects.
+            limit: Optional cap on the total number of issues returned.
+
+        Raises:
+            JIRAError: If Jira rejects the query or a request fails.
+        """
         return self._paginate(
             query=query,
             max_results=max_results,
             specific_fields=specific_fields,
-            jira_err_limit=jira_err_count,
             json_result=json_result,
+            limit=limit,
         )
 
+    @staticmethod
+    def _find_issue_meta(meta: dict, project_key: str, issue_type: str) -> tuple[dict | None, dict | None]:
+        if (project_meta := next((p for p in meta["projects"] if p["key"] == project_key), None)) is None:
+            return None, None
+        issue_meta = next((it for it in project_meta["issuetypes"] if it["name"].lower() == issue_type.lower()), None)
+        return project_meta, issue_meta
+
     def _fetch_via_createmeta(self, project_key: str, issue_type: str) -> dict:
-        meta = self.jira_client.createmeta(
-            projectKeys=project_key, issuetypeNames=issue_type, expand="projects.issuetypes.fields"
-        )
-        if not (project_meta := next((p for p in meta["projects"] if p["key"] == project_key), None)):
+        expand = "projects.issuetypes.fields"
+        meta = self.jira_client.createmeta(projectKeys=project_key, issuetypeNames=issue_type, expand=expand)
+        project_meta, issue_meta = self._find_issue_meta(meta, project_key, issue_type)
+        if issue_meta is None:
+            # `issuetypeNames` is matched case-sensitively server-side, so a wrong-cased name comes back empty.
+            meta = self.jira_client.createmeta(projectKeys=project_key, expand=expand)
+            project_meta, issue_meta = self._find_issue_meta(meta, project_key, issue_type)
+        if project_meta is None:
             raise ValueError(f"Project {project_key} not found in metadata")
-        issue_meta = next((it for it in project_meta["issuetypes"] if it["name"].lower() == issue_type.lower()), None)
-        if not issue_meta:
+        if issue_meta is None:
             raise ValueError(f"Issue type '{issue_type}' not found in project '{project_key}'")
         return issue_meta["fields"]
 
     def _fetch_via_issue_types_api(self, project_key: str, issue_type: str) -> dict:
-        issue_types = {t.name: t for t in self.jira_client.project_issue_types(project_key)}
-        field_list = self.jira_client.project_issue_fields(project_key, issue_types[issue_type].id)
+        issue_types = {t.name.lower(): t for t in self.jira_client.project_issue_types(project_key)}
+        if (matched := issue_types.get(issue_type.lower())) is None:
+            available = sorted(t.name for t in issue_types.values())
+            raise ValueError(
+                f"Issue type '{issue_type}' not found in project '{project_key}'. Available issue types: {available}"
+            )
+        field_list = self.jira_client.project_issue_fields(project_key, matched.id)
         return {f.fieldId: f.raw for f in field_list}
 
     def get_project_fields_metadata(self, project_key: str, issue_type: str) -> dict:
@@ -161,40 +223,70 @@ class JiraBase(ABC):
             return None
         return allowed
 
+    def get_create_fields(self, project_key: str, issue_type: str) -> list[CreateField]:
+        """Fields for creating an issue: required first, each with its allowed values as readable labels."""
+        result = [
+            CreateField(
+                id=field_id,
+                name=meta.get("name", field_id),
+                required=bool(meta.get("required")),
+                type=(meta.get("schema") or {}).get("type"),
+                allowed_values=(
+                    [allowed_value_label(v) for v in allowed] if (allowed := meta.get("allowedValues")) else None
+                ),
+            )
+            for field_id, meta in self.get_project_fields_metadata(project_key, issue_type).items()
+        ]
+        return sorted(result, key=lambda f: (not f["required"], f["name"]))
+
     @staticmethod
     def _is_value_allowed(value: Any, allowed_values: list[Any]) -> bool:
-        allowed_names = {av.get("name") for av in allowed_values}
-        allowed_keys = {av.get("key") for av in allowed_values}
-        allowed_values = allowed_names | allowed_keys
-        return describe_allowed_value(value, allowed_values=allowed_values)
+        allowed = {av.get(key) for av in allowed_values for key in ALLOWED_VALUE_KEYS}
+        allowed.discard(None)
+        return describe_allowed_value(value, allowed_values=allowed)
 
-    def validate_fields(self, project_key: str, issue_type: str, fields: dict) -> None:  # pylint: disable=R1260
-        fields_metadata = self.get_project_fields_metadata(project_key=project_key, issue_type=issue_type)
-        for custom_field, value in fields.items():
-            if custom_field not in fields_metadata:
+    @staticmethod
+    def _check_field_type(field_id: str, field_type: str | None, value: Any) -> None:
+        if (check := FIELD_TYPE_CHECKS.get(field_type or "")) and not isinstance(value, check.python_types):
+            raise ValueError(f"Field '{field_id}' must be {check.label}")
+
+    def _validate_against_metadata(self, fields_metadata: dict, fields: dict, context: str) -> None:
+        for field_id, value in fields.items():
+            if field_id not in fields_metadata:
+                raise ValueError(f'Invalid field(s) for {context}: "{field_id}"')
+            field_meta = fields_metadata[field_id]
+            if (allowed_value := field_meta.get("allowedValues")) and not self._is_value_allowed(
+                value=value, allowed_values=allowed_value
+            ):
                 raise ValueError(
-                    f'Invalid field(s) for project "{project_key}", issue type "{issue_type}": "{custom_field}"'
+                    f"Invalid value '{value}' for field '{field_id}' in {context}. "
+                    f"The allowed values are: {json.dumps(allowed_value, indent=4, sort_keys=True)}"
                 )
-            if allowed_value := fields_metadata[custom_field].get("allowedValues"):
-                if not self._is_value_allowed(value=value, allowed_values=allowed_value):
-                    raise ValueError(
-                        f"Invalid value '{value}' for field '{custom_field}' in project '{project_key}' "
-                        f"with issue type '{issue_type}'."
-                        f"The allowed values are: {json.dumps(allowed_value, indent=4, sort_keys=True)}"
-                    )
-            field_type = fields_metadata[custom_field]["schema"]["type"]
-            if field_type == "string" and not isinstance(value, str):
-                raise ValueError(f"Field '{custom_field}' must be a string")
-            if field_type == "number" and not isinstance(value, int | float):
-                raise ValueError(f"Field '{custom_field}' must be a number")
-            if field_type == "boolean" and not isinstance(value, bool):
-                raise ValueError(f"Field '{custom_field}' must be a boolean")
-            if field_type == "array" and not isinstance(value, list):
-                raise ValueError(f"Field '{custom_field}' must be an array")
-            if field_type == "object" and not isinstance(value, dict):
-                raise ValueError(f"Field '{custom_field}' must be an object")
-            if field_type == "issuetype" and not isinstance(value, dict):
-                raise ValueError(f"Field '{custom_field}' must be an issue type")
+            self._check_field_type(field_id, field_meta.get("schema", {}).get("type"), value)
+
+    def validate_fields(
+        self, project_key: str, issue_type: str, fields: dict, fields_metadata: dict | None = None
+    ) -> None:
+        """Validate `fields`; pass `fields_metadata` to reuse an already-fetched result."""
+        if fields_metadata is None:
+            fields_metadata = self.get_project_fields_metadata(project_key=project_key, issue_type=issue_type)
+        self._validate_against_metadata(
+            fields_metadata, fields, context=f'project "{project_key}", issue type "{issue_type}"'
+        )
+
+    @staticmethod
+    def _canonical_issue_type(fields_metadata: dict, issue_type: str) -> str:
+        """Return the issue type's real casing (e.g. 'task' -> 'Task'), or `issue_type` if metadata lacks it."""
+        allowed = fields_metadata.get("issuetype", {}).get("allowedValues", [])
+        return next((av["name"] for av in allowed if av.get("name", "").lower() == issue_type.lower()), issue_type)
+
+    @staticmethod
+    def _merge_custom_fields(issue_fields: dict[str, Any], custom_fields: dict | None) -> dict[str, Any]:
+        """Merge `custom_fields` in, refusing to let them override the dedicated arguments."""
+        for key, value in (custom_fields or {}).items():
+            if key in issue_fields and issue_fields[key] != value:
+                raise ValueError(f"custom_fields['{key}'] conflicts with the dedicated argument for '{key}'")
+        return {**(custom_fields or {}), **issue_fields}
 
     def create_issue(
         self,
@@ -213,79 +305,108 @@ class JiraBase(ABC):
         }
         if assignee:
             issue_fields["assignee"] = self._format_assignee(assignee)
-        if custom_fields:
-            issue_fields = issue_fields | custom_fields
-        self.validate_fields(project_key=project_key, issue_type=issue_type, fields=issue_fields)
+        issue_fields = self._merge_custom_fields(issue_fields, custom_fields)
+        fields_metadata = self.get_project_fields_metadata(project_key=project_key, issue_type=issue_type)
+        issue_fields["issuetype"] = {"name": self._canonical_issue_type(fields_metadata, issue_type)}
+        self.validate_fields(project_key, issue_type, issue_fields, fields_metadata=fields_metadata)
         issue = self.jira_client.create_issue(fields=issue_fields)
         self.logger.info(f"Issue {issue.key} created successfully.")
         return issue
 
     def update_issue(self, issue_key: str, fields_to_update: dict) -> Issue | None:
+        """Update an issue after validating `fields_to_update` against its edit metadata.
+
+        Raises:
+            ValueError: If a field is not editable or a value is invalid (always raised).
+        """
+        check_issue_ref(issue_key)
         try:
             issue = self.jira_client.issue(issue_key)
-            self.validate_fields(
-                project_key=issue.fields.project.key, issue_type=issue.fields.issuetype.name, fields=fields_to_update
-            )
+            edit_fields = self.jira_client.editmeta(issue_key)["fields"]
+            self._validate_against_metadata(edit_fields, fields_to_update, context=f'issue "{issue_key}"')
             issue.update(fields=fields_to_update)
             self.logger.info(f"Issue {issue.key} updated successfully.")
             return issue
-        except JIRAError as err:
-            self.logger.error(f"JIRAError while updating issue: {err.text}")
-            return None
+        except ValueError:
+            raise
         except Exception as err:
-            self.logger.exception(f"Unexpected error: {err}")
+            self._handle_error(f"Failed to update issue {issue_key}", err)
             return None
 
     def delete_issue(self, issue_key: str) -> bool:
+        check_issue_ref(issue_key)
         try:
-            issue = self.get_issue_by_key(key=issue_key, json_result=False)
+            issue = self.jira_client.issue(issue_key)
             issue.delete()
             self.logger.info(f"Issue {issue_key} deleted successfully.")
             return True
-        except JIRAError as err:
-            self.logger.error(f"JIRAError while deleting issue: {err.text}")
-            return False
         except Exception as err:
-            self.logger.exception(f"Unexpected error: {err}")
+            self._handle_error(f"Failed to delete issue {issue_key}", err)
             return False
 
     def add_comment(self, issue: str, comment: str) -> None:
+        check_issue_ref(issue)
         self.jira_client.add_comment(issue=issue, body=comment)
         self.logger.debug(f"Comment added to issue {issue} successfully.")
 
+    def get_link_types(self) -> list[dict[str, str]]:
+        """Return the instance's issue link types as `{name, inward, outward}` dicts."""
+        return [
+            {"name": link_type.name, "inward": link_type.inward, "outward": link_type.outward}
+            for link_type in self.jira_client.issue_link_types()
+        ]
+
     def _get_available_link_types(self) -> set[str]:
-        try:
-            return {link_type.name for link_type in self.jira_client.issue_link_types()}
-        except Exception as err:
-            self.logger.exception(f"Failed to retrieve link types from JIRA. \n{err}")
-            return set()
+        return {link_type["name"] for link_type in self.get_link_types()}
 
     def create_link(self, issue_key: str, link_type: str, in_issue_key: str) -> bool:
-        available_link_types = self._get_available_link_types()
-        if link_type not in available_link_types:
-            raise ValueError(f"Invalid link type '{link_type}'. Available link types: {available_link_types}")
+        check_issue_ref(issue_key)
+        check_issue_ref(in_issue_key)
+        try:
+            available_link_types = self._get_available_link_types()
+        except Exception as err:
+            self._handle_error("Failed to retrieve link types from JIRA", err)
+            return False
+        if (canonical := {name.lower(): name for name in available_link_types}.get(link_type.lower())) is None:
+            raise ValueError(f"Invalid link type '{link_type}'. Available link types: {sorted(available_link_types)}")
         try:
             self.jira_client.create_issue_link(
-                type=link_type,
+                type=canonical,
                 inwardIssue=issue_key,
                 outwardIssue=in_issue_key,
             )
             self.logger.info(f"Link between {issue_key} and {in_issue_key} was created")
             return True
-        except JIRAError as err:
-            self.logger.exception(f"JIRAError - Link between {issue_key} and {in_issue_key} was not created\n{err}")
-            return False
         except Exception as err:
-            self.logger.exception(f"Exception - Link between {issue_key} and {in_issue_key} was not created\n{err}")
+            self._handle_error(f"Link between {issue_key} and {in_issue_key} was not created", err)
             return False
 
-    def upload_attachment(self, issue_key: str, file_path: str) -> None:
+    def upload_attachment(self, issue_key: str, file_path: str) -> bool:
+        check_issue_ref(issue_key)
         try:
             self.jira_client.add_attachment(issue=issue_key, attachment=file_path)
-        except JIRAError as err:
-            self.logger.exception(f"JIRAError - Attachment {file_path} was not uploaded to issue {issue_key}\n{err}")
+            return True
         except Exception as err:
-            self.logger.exception(f"Exception - Attachment {file_path} was not uploaded to issue {issue_key}\n{err}")
+            self._handle_error(f"Attachment {file_path} was not uploaded to issue {issue_key}", err)
+            return False
+
+    def _fetch_transitions(self, issue_key: str) -> list[dict]:
+        """Single place that fetches transitions; `fields` is expanded so callers can inspect the screen."""
+        return self.jira_client.transitions(issue_key, expand="transitions.fields")
+
+    def get_transitions(self, issue_key: str) -> list[dict[str, str]]:
+        """Return the transitions currently available for an issue as `{id, name}` dicts."""
+        check_issue_ref(issue_key)
+        return [{"id": t["id"], "name": t["name"]} for t in self._fetch_transitions(issue_key)]
+
+    def _resolve_transition(self, issue_key: str, transition_name: str) -> dict:
+        transitions = self._fetch_transitions(issue_key)
+        if transition := next((t for t in transitions if t["name"].lower() == transition_name.lower()), None):
+            return transition
+        raise ValueError(
+            f"Transition '{transition_name}' not found for issue {issue_key}. "
+            f"Available transitions: {sorted(t['name'] for t in transitions)}"
+        )
 
     def transition_issue(
         self,
@@ -294,27 +415,34 @@ class JiraBase(ABC):
         fields: dict | None = None,
         comment: str | None = None,
     ) -> bool:
+        """Transition an issue by name (case-insensitive), optionally with a comment.
+
+        Jira silently drops a transition comment when the transition screen has no comment field,
+        so in that case the comment is added separately after the transition succeeds.
+        """
+        check_issue_ref(issue_key)
+        needs_separate_comment = False
         try:
-            transitions = self.jira_client.transitions(issue_key)
-            transition_names = {t["name"] for t in transitions}
-            if transition_name not in transition_names:
-                self.logger.error(
-                    f"Transition '{transition_name}' not found for issue {issue_key}. "
-                    f"\nAvailable transitions: {transition_names}"
-                )
-                return False
-            transition_id = next((t["id"] for t in transitions if t["name"].lower() == transition_name.lower()), None)
-            if not transition_id:
-                self.logger.error(f"Transition '{transition_name}' not found for issue {issue_key}")
-                return False
+            transition = self._resolve_transition(issue_key, transition_name)
+            needs_separate_comment = bool(comment) and "comment" not in transition.get("fields", {})
             self.jira_client.transition_issue(
-                issue=issue_key, transition=transition_id, fields=fields or {}, comment=comment or None
+                issue=issue_key,
+                transition=transition["id"],
+                fields=fields or {},
+                comment=None if needs_separate_comment else comment or None,
             )
-            self.logger.info(f"Issue {issue_key} transitioned to '{transition_name}'")
-            return True
-        except JIRAError as err:
-            self.logger.exception(f"JIRAError during transition of {issue_key}: {err}")
-            return False
         except Exception as err:
-            self.logger.exception(f"Unexpected error during transition of {issue_key}: {err}")
+            self._handle_error(f"Failed to transition {issue_key} to '{transition_name}'", err)
             return False
+        self.logger.info(f"Issue {issue_key} transitioned to '{transition_name}'")
+        if needs_separate_comment:
+            self._comment_after_transition(issue_key, comment)
+        return True
+
+    def _comment_after_transition(self, issue_key: str, comment: str | None) -> None:
+        """The transition already happened, so a comment failure is reported but does not undo its success."""
+        try:
+            if comment:
+                self.add_comment(issue=issue_key, comment=comment)
+        except Exception as err:
+            self._handle_error(f"Issue {issue_key} was transitioned but the comment was not added", err)

python_jira_plus/jira_cloud.py

@@ -1,36 +1,18 @@
 # jira_cloud.py
 
-import logging
-import time
+from functools import partial
+from typing import Any
 
 import requests
 from jira import JIRA, Issue, JIRAError
 from jira.client import ResultList
 
-from python_jira_plus.jira_base import JiraBase, UrlScheme
+from python_jira_plus.jira_base import JiraBase
 
 
 class JiraCloud(JiraBase):
     use_createmeta = True
 
-    def __init__(
-        self,
-        base_url: str | None = None,
-        urllib3_log_level: int = logging.WARNING,
-        jira_username: str | None = None,
-        jira_token: str | None = None,
-        verify_ssl: bool = True,
-        url_scheme: UrlScheme = UrlScheme.HTTPS,
-    ) -> None:
-        super().__init__(
-            base_url=base_url,
-            urllib3_log_level=urllib3_log_level,
-            jira_username=jira_username,
-            jira_token=jira_token,
-            verify_ssl=verify_ssl,
-            url_scheme=url_scheme,
-        )
-
     def create_connection(self, timeout: int = 580) -> JIRA:
         jira_client = JIRA(
             basic_auth=(self.jira_username, self.jira_token),
@@ -46,64 +28,60 @@ class JiraCloud(JiraBase):
     def _format_assignee(self, assignee: str) -> dict:
         return {"accountId": assignee}
 
+    @staticmethod
+    def _split_page(page: Any, json_result: bool) -> tuple[list, bool, str | None]:
+        """Return (issues, is_last, next_page_token) from a search page; an empty page counts as the last."""
+        if not page:
+            return [], True, None
+        if json_result:
+            return page.get("issues", []), page["isLast"], page.get("nextPageToken")
+        return list(page), page.isLast, page.nextPageToken
+
     def _paginate(
         self,
         query: str,
         max_results: int,
         specific_fields: str | list[str],
-        jira_err_limit: int,
         json_result: bool,
+        limit: int | None = None,
     ) -> ResultList[Issue] | list:
-        all_issues = []
-        retries = 0
-        page = None
-        while True:  # pylint: disable=while-used
-            try:
-                next_token = None
-                if page is not None:
-                    next_token = page.get("nextPageToken") if json_result else page.nextPageToken
-
-                self.logger.debug(f"Fetching issues from startAt={len(all_issues)}")
-                page = self.jira_client.enhanced_search_issues(
-                    jql_str=query,
-                    nextPageToken=next_token,
-                    maxResults=max_results,
-                    fields=specific_fields,
-                    json_result=json_result,
-                )
-                if not page:
-                    break
-
-                all_issues += page["issues"] if json_result else page
-                if page["isLast"] if json_result else page.isLast:
-                    break
-                retries = 0
-            except JIRAError as err:
-                if err.status_code == 400:
-                    self.logger.error(f"Bad Request: {err.text}")
-                    raise JIRAError(f"Bad Request: {err.text}") from err
-                retries += 1
-                self.logger.warning(f"Retry {retries}/{jira_err_limit} after JIRAError: {err}")
-                if retries >= jira_err_limit:
-                    self.logger.exception("Max retries exceeded.")
-                    return []
-                time.sleep(300 if retries == jira_err_limit - 1 else 90)
-        return all_issues
+        all_issues: list = []
+        next_token = None
+        while limit is None or len(all_issues) < limit:  # pylint: disable=while-used
+            self.logger.debug(f"Fetching issues from startAt={len(all_issues)}")
+            page_size = max_results if limit is None else min(max_results, limit - len(all_issues))
+            fetch = partial(
+                self.jira_client.enhanced_search_issues,
+                jql_str=query,
+                nextPageToken=next_token,
+                maxResults=page_size,
+                fields=specific_fields,
+                json_result=json_result,
+            )
+            issues, is_last, next_token = self._split_page(fetch(), json_result)
+            all_issues += issues
+            if is_last or not issues:
+                break
+        return all_issues if limit is None else all_issues[:limit]
 
     def get_account_data(self, user_mail: str) -> list[dict]:
         response = requests.get(
             f"{self.server}/rest/api/3/user/search",
             params={"query": user_mail},
             auth=(self.jira_username, self.jira_token),
+            verify=self.verify_ssl,
             timeout=30,
         )
         response.raise_for_status()
         return response.json()
 
+    def _first_account(self, query: str) -> dict:
+        if not (data := self.get_account_data(user_mail=query)):
+            raise ValueError(f"No Jira user found matching '{query}'")
+        return data[0]
+
     def get_account_id(self, user_mail: str) -> str:
-        data = self.get_account_data(user_mail=user_mail)
-        return data[0]["accountId"]
+        return self._first_account(user_mail)["accountId"]
 
     def get_account_display_name(self, user_display_name: str) -> str:
-        data = self.get_account_data(user_mail=user_display_name)
-        return data[0]["displayName"]
+        return self._first_account(user_display_name)["displayName"]

python_jira_plus/jira_on_premise.py

@@ -1,7 +1,7 @@
 # jira_on_premise.py
 
 import logging
-import time
+from functools import partial
 
 from jira import JIRA, Issue, JIRAError
 from jira.client import ResultList
@@ -20,6 +20,7 @@ class JiraOnPremise(JiraBase):
         verify_ssl: bool = True,
         sso: bool = False,
         url_scheme: UrlScheme = UrlScheme.HTTPS,
+        raise_on_error: bool = False,
     ) -> None:
         self.sso = sso  # must be set before super().__init__ — create_connection reads it
         super().__init__(
@@ -29,6 +30,7 @@ class JiraOnPremise(JiraBase):
             jira_token=jira_token,
             verify_ssl=verify_ssl,
             url_scheme=url_scheme,
+            raise_on_error=raise_on_error,
         )
         use_legacy = Version(".".join(str(x) for x in self.server_version)) < Version("9.0.0")
         self.logger.debug(
@@ -37,6 +39,9 @@ class JiraOnPremise(JiraBase):
         )
         self.use_createmeta = use_legacy
 
+    def _requires_username(self) -> bool:
+        return self.sso  # token auth needs no username
+
     def create_connection(self, timeout: int = 580) -> JIRA:
         auth = (
             {"token_auth": self.jira_token} if not self.sso else {"basic_auth": (self.jira_username, self.jira_token)}
@@ -56,41 +61,27 @@ class JiraOnPremise(JiraBase):
         query: str,
         max_results: int,
         specific_fields: str | list[str],
-        jira_err_limit: int,
         json_result: bool,
+        limit: int | None = None,
     ) -> ResultList[Issue] | list:
+        cap = max_results if limit is None else limit  # without `limit`, max_results is also the total cap
         start_at = 0
-        all_issues = []
-        retries = 0
-        while True:  # pylint: disable=while-used
-            try:
-                self.logger.debug(f"Fetching issues from startAt={start_at}")
-                page = self.jira_client.search_issues(
-                    jql_str=query,
-                    startAt=start_at,
-                    maxResults=max_results,
-                    fields=specific_fields,
-                    json_result=json_result,
-                )
-                if not page:
-                    break
-
-                all_issues += page["issues"] if json_result else page
-                if json_result:
-                    start_at += page["maxResults"]
-                else:
-                    start_at += page.maxResults
-                if start_at >= max_results:
-                    break
-                retries = 0
-            except JIRAError as err:
-                if err.status_code == 400:
-                    self.logger.error(f"Bad Request: {err.text}")
-                    raise JIRAError(f"Bad Request: {err.text}") from err
-                retries += 1
-                self.logger.warning(f"Retry {retries}/{jira_err_limit} after JIRAError: {err}")
-                if retries >= jira_err_limit:
-                    self.logger.exception("Max retries exceeded.")
-                    return []
-                time.sleep(300 if retries == jira_err_limit - 1 else 90)
-        return all_issues
+        all_issues: list = []
+        while start_at < cap:  # pylint: disable=while-used
+            self.logger.debug(f"Fetching issues from startAt={start_at}")
+            fetch = partial(
+                self.jira_client.search_issues,
+                jql_str=query,
+                startAt=start_at,
+                maxResults=min(max_results, cap - start_at),
+                fields=specific_fields,
+                json_result=json_result,
+            )
+            page = fetch()
+            if not (issues := (page.get("issues") if json_result else list(page)) if page else None):
+                break
+            all_issues += issues
+            start_at += len(issues)
+            if start_at >= (page["total"] if json_result else page.total):
+                break
+        return all_issues[:cap]

python_jira_plus/types.py

@@ -0,0 +1,9 @@
+from typing import TypedDict
+
+
+class CreateField(TypedDict):
+    id: str
+    name: str
+    required: bool
+    type: str | None
+    allowed_values: list[str] | None

{python_jira_plus-3.2.0.dist-info → python_jira_plus-4.1.0.dist-info}/METADATA

@@ -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-4.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+python_jira_plus/__init__.py,sha256=IwvlvL8KpeiSyeFh_DKLAqlGcHfZk7JINVUAGFRdYTo,801
+python_jira_plus/consts.py,sha256=YkuTHnXbP7JFC-u-7O3Kq_xf1I0x5djZuWgA5D8eDzw,669
+python_jira_plus/describe_allowed_value.py,sha256=fWfq0DkvJ2zmNIUXPH5rO5OgcY69bUqBIfTPQyxBt5E,1287
+python_jira_plus/helpers.py,sha256=DZybIN1zoW2QtT9WXJ2T45Lphtmym-GfG6gHOrT-AHI,686
+python_jira_plus/jira_base.py,sha256=SEObK7QW-Z6YNy4H7XXylagSNNLienZp0Nedopr1TS0,20143
+python_jira_plus/jira_cloud.py,sha256=CfkJTgf6j3wu7AnUI6BnykHRIL0XhDMtk0PejMiAsjg,3208
+python_jira_plus/jira_on_premise.py,sha256=8GDUDzJ6FYQQgSjbZs01cP9WBvplU5myIG-x6Ykw0hs,3240
+python_jira_plus/types.py,sha256=KxMR3Iv1ztmZjr9nhkdTpiyB9x7Mu1hrwDBBUuWdOi8,164
+python_jira_plus-4.1.0.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
+python_jira_plus-4.1.0.dist-info/METADATA,sha256=OnG9XYFlZnIWSsYGX1oypuHWpqXQWlUlXIJKSCCPJA0,4836
+python_jira_plus-4.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_jira_plus-4.1.0.dist-info/top_level.txt,sha256=3DxBdmf_naggoqDHSvLstG_GX3bW2XXYYorBDybBUiA,17
+python_jira_plus-4.1.0.dist-info/RECORD,,

{python_jira_plus-3.2.0.dist-info → python_jira_plus-4.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_jira_plus-3.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-python_jira_plus/__init__.py,sha256=HMlPp5HOfdEO3VYE7Zc2qfhLsIPpPJ9wQaUojhCOp0k,729
-python_jira_plus/consts.py,sha256=pkMp6dZUDjEwqa9OucBIeSs3mxnQt4KXxIpyuyHmY8A,33
-python_jira_plus/describe_allowed_value.py,sha256=fWfq0DkvJ2zmNIUXPH5rO5OgcY69bUqBIfTPQyxBt5E,1287
-python_jira_plus/jira_base.py,sha256=FEdw86I5kh8QUD2ulRNvz69R671Iqohts9DiAUTKQaQ,13875
-python_jira_plus/jira_cloud.py,sha256=5PsyaX0oPoTTq0HBTVlGeIbtt8Zc45qqeyCQlfoYVls,3795
-python_jira_plus/jira_on_premise.py,sha256=lueq9Glo8gluHfQcorlm7SSyT6eGzx4r94UTOrynNP0,3549
-python_jira_plus-3.2.0.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
-python_jira_plus-3.2.0.dist-info/METADATA,sha256=6crZgWe_uZEXKINRoAb5K6sp-ArFZmdYvFfyPfMSSXA,4253
-python_jira_plus-3.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_jira_plus-3.2.0.dist-info/top_level.txt,sha256=3DxBdmf_naggoqDHSvLstG_GX3bW2XXYYorBDybBUiA,17
-python_jira_plus-3.2.0.dist-info/RECORD,,