Merge pull request #3 from en-ver/dev

Validation and other improvements

docs/index.md

@@ -0,0 +1,3 @@
+# jira2py
+
+The documentation WIP

examples/fields_examples.py

@@ -1,16 +1,25 @@
 from jira2py import Jira
-import os
 from dotenv import load_dotenv
+import os
 
-"""Load .env variables"""
 load_dotenv()
 
-"""Create a Jira instance"""
 jira = Jira(
-    url=os.getenv("JIRA_URL", ""),
-    user=os.getenv("JIRA_USER", ""),
-    api_token=os.getenv("JIRA_API_TOKEN", ""),
+    jira_url=os.environ.get("JIRA_URL"),
+    jira_user=os.environ.get("JIRA_USER"),
+    jira_api_token=os.environ.get("JIRA_API_TOKEN"),
 )
 
+"""Create fields instance"""
+fields = jira.fields()
+
 """Get the list of Jira fields with its metadata"""
-fields = jira.fields().get()
+jira_fields = fields.get()
+
+"""Get the field id by its name"""
+field_ids = fields.get_field_id(["Summary", "Reporter", "Parent"])
+
+"""Get the field id by its id"""
+field_names = fields.get_field_name(["summary", "reporter", "parent"])
+
+"""Follow https://en-ver.github.io/jira2py/ for more details"""

examples/issue_examples.py

@@ -1,34 +1,41 @@
 from jira2py import Jira
-import os
 from dotenv import load_dotenv
+import os
 
-"""Load .env variables"""
 load_dotenv()
 
-"""Create a Jira instance"""
 jira = Jira(
-    url=os.getenv("JIRA_URL", ""),
-    user=os.getenv("JIRA_USER", ""),
-    api_token=os.getenv("JIRA_API_TOKEN", ""),
+    jira_url=os.environ.get("JIRA_URL"),
+    jira_user=os.environ.get("JIRA_USER"),
+    jira_api_token=os.environ.get("JIRA_API_TOKEN"),
 )
+issue_key = os.environ.get("ISSUE_KEY")
 
 """Create an Issue instance"""
-issue = jira.issue()
+issue = jira.issue(issue_key)
 
 """Get Issue details"""
-response = issue.get("PRJ-1111")  # issue object including the issue details
-names = response["names"]  # field ID-name mapping
-fields = response["fields"]  # field ID-name mapping
-status = fields["status"]["name"]  # status field value
-summary = fields["summary"]  # summary field value
+issue_json = issue.get(fields=["status", "summary"])  # Raw JSON reposnse form jira API
+names = issue_json["names"]  # Field ID-name mapping
+fields = issue_json["fields"]  # Fields of the issues
+status = issue_json["fields"]["status"]["name"]  # Status field value
+summary = issue_json.get("fields", {}).get("summary", None)  # Summary field value
 
 """Update "summary" field"""
-response = issue.edit(key="PRJ-1111", fields={"summary": f"Test summary"})
-
-"""Get changelog of the issue"""
-search_first_page = issue.get_changelogs(
-    "PRJ-1111"
-)  # Long changelogs returned paginated
-search_second_page = issue.get_changelogs(
-    "PRJ-1111", start_at=50, max_results=50
-)  # set the # of item to start from load and items to load to get the next page of results
+enable_edit = False  # put here True to let teh script proceed with edit
+if enable_edit:
+    edit_response_json = issue.edit(fields={"summary": f"Test summary"})
+
+"""Get the the first page of the changelog"""
+changelog_page_json = issue.changelog_page()
+
+"""Get the changelog first page filtered by field ids"""
+changelog_page_json_filtered = issue.changelog_page(fields=["issuetype", "labels"])
+
+"""Get full changelog of the issue"""
+full_changelog_list = issue.changelog_all_pages()
+
+"""Get full changelog of the issue filtered by field ids"""
+full_changelog_list_filtered = issue.changelog_all_pages(fields=["issuetype", "labels"])
+
+"""Follow https://en-ver.github.io/jira2py/ for more details"""

examples/jql_examples.py

@@ -0,0 +1,26 @@
+from jira2py import Jira
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+jira = Jira(
+    jira_url=os.environ.get("JIRA_URL"),
+    jira_user=os.environ.get("JIRA_USER"),
+    jira_api_token=os.environ.get("JIRA_API_TOKEN"),
+)
+jql = os.getenv("JQL", None)
+
+"""Create search instance"""
+search = jira.jql(jql=jql)
+
+"""Search and return all fields except priority, status category changedate, and status"""
+search_results = search.get_page(
+    fields=["*all", "-priority", "-statuscategorychangedate", "-status"],
+    expand="names,changelog",
+)
+
+"""Get all pages of search results using paginated method"""
+all_issues = search.get_all_pages(fields=["*all"], expand="names,changelog")
+
+"""Follow https://en-ver.github.io/jira2py/ for more details"""

jira2py/fields.py

@@ -1,10 +1,93 @@
 from .jirabase import JiraBase
+from pydantic import validate_call
+
+"""
+This module provides the `Fields` class, which allows interaction with Jira field metadata.
+
+The `Fields` class enables users to retrieve and manage information about fields available in a Jira instance. 
+It includes methods for listing all fields, retrieving field IDs based on field names, and retrieving field 
+names based on field IDs. 
+
+This functionality simplifies working with Jira's field data for custom integrations and automation.
+"""
 
 
 class Fields(JiraBase):
 
-    def get(self) -> list[dict]:
+    def __init__(self, auth_kwargs: tuple):
 
-        kwargs = {"method": "GET", "context_path": "field"}
+        self._set_jira_auth(auth_kwargs)
+
+    def _load_fields(self):
 
+        kwargs = {"method": "GET", "context_path": "field"}
         return self._request_jira(**kwargs)
+
+    def _get_field_attr(
+        self,
+        in_attr_name: str,
+        in_attr_values: str | list[str],
+        out_attr_name: str | list[str],
+    ):
+
+        fields = self._load_fields()
+
+        return [
+            field.get(out_attr_name, None)
+            for attr_value in in_attr_values
+            for field in fields
+            if field.get(in_attr_name, None) == attr_value
+        ]
+
+    def get(self) -> list[dict]:
+        """
+        Retrieve all available fields in the Jira instance.
+
+        This method fetches a list of all fields currently available in the Jira instance,
+        including standard and custom fields. It provides comprehensive metadata for each
+        field, which can be used for various integrations and automations.
+
+        Returns:
+            list[dict]: A list of dictionaries where each dictionary contains metadata
+                        about a field (e.g., field ID, name, and other attributes).
+        """
+
+        return self._load_fields()
+
+    @validate_call
+    def get_field_id(self, field_names: list[str]) -> list[str]:
+        """
+        Retrieve the IDs of fields based on their names.
+
+        This method takes a list of field names and returns a list of corresponding field IDs
+        available in the Jira instance.
+
+        Args:
+            field_names (list[str]): A list of field names to search for.
+
+        Returns:
+            list[str]: A list of field IDs that correspond to the provided field names.
+        """
+
+        return self._get_field_attr(
+            in_attr_name="name", in_attr_values=field_names, out_attr_name="id"
+        )
+
+    @validate_call
+    def get_field_name(self, field_ids: list[str]) -> list[str]:
+        """
+        Retrieve the names of fields based on their IDs.
+
+        This method takes a list of field IDs and returns a list of corresponding field names
+        available in the Jira instance.
+
+        Args:
+            field_ids (list[str]): A list of field IDs to search for.
+
+        Returns:
+            list[str]: A list of field names that correspond to the provided field IDs.
+        """
+
+        return self._get_field_attr(
+            in_attr_name="id", in_attr_values=field_ids, out_attr_name="name"
+        )