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

{python_jira_plus-4.0.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: 4.0.0
+Version: 4.1.0
 Summary: Enhanced Python client for JIRA with better error handling, pagination, and metadata validation.
 Author: Avi Zaguri
 License: MIT

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-jira-plus"
-version = "4.0.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"

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

@@ -9,6 +9,7 @@ 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
+from python_jira_plus.types import CreateField
 
 BASIC_FIELDS = [
     "created",
@@ -25,4 +26,12 @@ BASIC_FIELDS = [
     "resolution",
     "parent",
 ]
-__all__ = ["JiraBase", "JiraCloud", "JiraOnPremise", "UrlScheme", "BASIC_FIELDS", "describe_allowed_value"]
+__all__ = [
+    "JiraBase",
+    "JiraCloud",
+    "JiraOnPremise",
+    "UrlScheme",
+    "BASIC_FIELDS",
+    "describe_allowed_value",
+    "CreateField",
+]

{python_jira_plus-4.0.0 → python_jira_plus-4.1.0}/python_jira_plus/consts.py

@@ -19,3 +19,4 @@ FIELD_TYPE_CHECKS = {
     "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")

{python_jira_plus-4.0.0 → python_jira_plus-4.1.0}/python_jira_plus/jira_base.py

@@ -19,6 +19,8 @@ from python_jira_plus.consts import (
     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):
@@ -125,6 +127,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
     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:
@@ -220,6 +223,22 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
             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 = {av.get(key) for av in allowed_values for key in ALLOWED_VALUE_KEYS}
@@ -300,6 +319,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
         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)
             edit_fields = self.jira_client.editmeta(issue_key)["fields"]
@@ -314,6 +334,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
             return None
 
     def delete_issue(self, issue_key: str) -> bool:
+        check_issue_ref(issue_key)
         try:
             issue = self.jira_client.issue(issue_key)
             issue.delete()
@@ -324,6 +345,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
             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.")
 
@@ -338,6 +360,8 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
         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:
+        check_issue_ref(issue_key)
+        check_issue_ref(in_issue_key)
         try:
             available_link_types = self._get_available_link_types()
         except Exception as err:
@@ -358,6 +382,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
             return False
 
     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)
             return True
@@ -371,6 +396,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
 
     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:
@@ -394,6 +420,7 @@ class JiraBase(ABC):  # pylint: disable=too-many-instance-attributes
         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:
             transition = self._resolve_transition(issue_key, transition_name)

python_jira_plus-4.1.0/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-4.0.0 → python_jira_plus-4.1.0/python_jira_plus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-jira-plus
-Version: 4.0.0
+Version: 4.1.0
 Summary: Enhanced Python client for JIRA with better error handling, pagination, and metadata validation.
 Author: Avi Zaguri
 License: MIT

{python_jira_plus-4.0.0 → python_jira_plus-4.1.0}/python_jira_plus.egg-info/SOURCES.txt

@@ -5,9 +5,11 @@ pyproject.toml
 python_jira_plus/__init__.py
 python_jira_plus/consts.py
 python_jira_plus/describe_allowed_value.py
+python_jira_plus/helpers.py
 python_jira_plus/jira_base.py
 python_jira_plus/jira_cloud.py
 python_jira_plus/jira_on_premise.py
+python_jira_plus/types.py
 python_jira_plus.egg-info/PKG-INFO
 python_jira_plus.egg-info/SOURCES.txt
 python_jira_plus.egg-info/dependency_links.txt
@@ -17,4 +19,5 @@ tests/test_describe_allowed_value.py
 tests/test_jira_cloud_integration.py
 tests/test_jira_cloud_write_integration.py
 tests/test_jira_plus.py
-tests/test_jira_plus_hardening.py
+tests/test_jira_plus_hardening.py
+tests/test_jira_plus_v41.py

python_jira_plus-4.1.0/tests/test_jira_plus_v41.py

@@ -0,0 +1,67 @@
+# pylint: disable=no-self-use
+from collections.abc import Callable
+from unittest.mock import MagicMock
+
+import pytest
+
+from python_jira_plus.helpers import check_issue_ref
+from python_jira_plus.jira_base import JiraBase
+from python_jira_plus.jira_cloud import JiraCloud
+
+BAD_KEY = "PROJ-1/../myself"
+ISSUE_METHODS: list[tuple[str, Callable[[JiraBase], object]]] = [
+    ("get_issue_by_key", lambda jp: jp.get_issue_by_key(BAD_KEY)),
+    ("update_issue", lambda jp: jp.update_issue(BAD_KEY, {"summary": "x"})),
+    ("delete_issue", lambda jp: jp.delete_issue(BAD_KEY)),
+    ("add_comment", lambda jp: jp.add_comment(BAD_KEY, "hi")),
+    ("upload_attachment", lambda jp: jp.upload_attachment(BAD_KEY, "f.txt")),
+    ("get_transitions", lambda jp: jp.get_transitions(BAD_KEY)),
+    ("transition_issue", lambda jp: jp.transition_issue(BAD_KEY, "Done")),
+    ("create_link (inward)", lambda jp: jp.create_link(BAD_KEY, "Blocks", "PROJ-2")),
+    ("create_link (outward)", lambda jp: jp.create_link("PROJ-2", "Blocks", BAD_KEY)),
+]
+
+
+class TestGetCreateFields:
+    def test_required_first_and_labels(self, jira_plus_cloud: JiraCloud) -> None:
+        jira_plus_cloud.get_project_fields_metadata = MagicMock(
+            return_value={
+                "customfield_1": {
+                    "name": "Severity",
+                    "required": False,
+                    "schema": {"type": "option"},
+                    "allowedValues": [{"value": "High", "id": "1"}, {"id": "2"}],
+                },
+                "summary": {"name": "Summary", "required": True, "schema": {"type": "string"}},
+            }
+        )
+        fields = jira_plus_cloud.get_create_fields("OK", "Bug")
+        assert [f["id"] for f in fields] == ["summary", "customfield_1"]
+        assert fields[0]["allowed_values"] is None
+        assert fields[1]["allowed_values"] == ["High", "2"]
+        assert fields[1]["type"] == "option"
+
+
+class TestIssueRefValidation:
+    @pytest.mark.parametrize("ref", ["PROJ-1", "proj-12", "10001", "AB_C-3"])
+    def test_valid(self, ref: str) -> None:
+        check_issue_ref(ref)
+
+    @pytest.mark.parametrize("ref", [BAD_KEY, "PROJ-1?x=1", "", "a b", "PROJ-1#x"])
+    def test_invalid(self, ref: str) -> None:
+        with pytest.raises(ValueError, match="Invalid issue key"):
+            check_issue_ref(ref)
+
+    @pytest.mark.parametrize("call", [c for _, c in ISSUE_METHODS], ids=[n for n, _ in ISSUE_METHODS])
+    def test_every_issue_method_rejects_before_any_request(
+        self, jira_plus_cloud: JiraCloud, call: Callable[[JiraBase], object]
+    ) -> None:
+        jira = jira_plus_cloud.jira_client
+        jira.reset_mock()
+        with pytest.raises(ValueError, match="Invalid issue key"):
+            call(jira_plus_cloud)  # raised even with raise_on_error=False
+        assert not jira.method_calls, jira.method_calls
+
+    def test_valid_key_still_reaches_jira(self, jira_plus_cloud: JiraCloud) -> None:
+        jira_plus_cloud.add_comment("PROJ-1", "hi")
+        jira_plus_cloud.jira_client.add_comment.assert_called_once_with(issue="PROJ-1", body="hi")