daiބddlZddlZddlZddlmZmZmZmZmZm Z m Z ddl m Z ddl m Z ddlmZmZddlZej$dk\rddlmZnddlmZdd lmZmZdd lmZdd lmZmZej:eZGd d eZ y)N)AnyBinaryIODictListOptionalUnioncast)warn) deprecated) HTTPErrorResponse))Literal)ApiNotFoundErrorApiPermissionError)AtlassianRestAPI)T_id T_resp_jsoncD(eZdZdZdededeffd Z dFdedeed eed ee d ee d e f fd Z dGdedee dee dee dee de f dZde fdZ dHdee deedeede fdZde dede fdZde fdZ de fdZdede fd Z d!e deeeeffd"Zd#e de fd$ZdId!e d%eedeefd&Zed'd() dJd!e d%eed*e deefd+Zd#e defd,Zd#e de fd-Zde fd.Zd#e de fd/Z d#e de fd0Z! dKd1ee"d2ee"d3eed4eed5eede f d6Z#d7e$eefde fd8Z% dLd:ede fd;Z& de fd<Z'd=e de fd>Z(d=e de fd?Z)de fd@Z*d=e de fdAZ+ dBe de fdCZ,dDe de fdEZ-dFedefdGZ. de fdHZ/de fdIZ0de fdJZ1de fdKZ2de fdLZ3de de fdMZ4de"de fdNZ5de dOe de fdPZ6 dOe de fdQZ7dOe dRede fdSZ8dOe dRedTe9de fdUZ:dOe dRede fdVZ; dWe de fdXZdZedWe de fd\Z?dWe de fd]Z@dWe d^ede fd_ZA de fd`ZB dae de fdbZCdMdceedde"d2e"de fdeZDde fdfZE dNdgedhedieedjeede f dkZFdle dme de fdnZGdle dme doe de fdpZH dOd3edde"d2e"deefdqZIdre deefdsZJ dPdgedtedjeedue fdvZK dHdwe dgedteedjeeduee f dxZLdwe fdyZMdwe dtedefdzZNdwe fd{ZOdwe fd|ZP dQdwe dhedee d}ee d~eedeedeedeefdZQdwe de fdZR dRdeedeed2e"fdZSdgefdZTdIdgedeefdZU dSdede dde"d2e"fdZV dHdeedeedeefdZW dHdeedeedeede fdZX dTdedeedeedde"d2e"de f dZY dUde de$eefdeefdZZ dVde de$ee e[e\dfdeede deef dZ]dUdede$ee fdeefdZ^dWde de$ee ffdZ_dXdedede fdZ`dNdeddee"d2ee"fdZa dNdededdee"d2ee"fdZbdefdZcdNdeddee"d2ee"fdZddede$eeffdZedIdedede"deefdZfdefdZgdIdedee fdZhdefdZidedefdZjdefdZkdYde de$eefde fdZldWde de$eefde fdZmdZdededede fdZndede fdZode de$eefde fdZpde de fdZqde de fdZrdedefdZsdedetfdZudedee fdZvdede fd„ZwdZdede fdĄZx d[dede$eefdeeeefdeeeefdeeede f dƄZydZdede$eefde fdDŽZzded9efdȄZ{dNded9eedeefdɄZ|defdʄZ}dId!e deefd˄Z~d\de$eefde deefd̄Zde fd΄ZdefdτZdefdЄZdIdededeefd҄Z dJdedOe dedeede f dӄZd!edefdՄZ dNdedee deefd؄Z dNdedee deefdلZdNdedee dee"fd܄Zdddddifdedededee deedeedeede defdZdede fdZ dNdede dededee deef dZdede de fdZdedeefdZdedede fdZ dNdedede$eedfdeefdZde fdZdede fdZdedefdZdefdZdedefdZ dNdedee deede fdZdefdZdedRed efdZdedRefdZdedRefdZdIdedeefdZdefdZdIdee deefdZ dGdeedeedeedeefdZdZdefdZdHdeedeedeefdZded efdZdedefdZdedefdZ dNdeded ed eed ee f d ZdNdeedeefd Z dHdeedeedeefdZ dGdeedeedeedTe$eedffdZ dHdeedeedeefdZdededefdZdefdZdefdZ d]dededefdZdZdZ d^dde"d2e"fdZ d_deedeedeedReedde"d2e"de de fdZdedede fdZdedefdZ dIdeefdZdNd ee deefd!ZdNd ee deefd"Zd#e$eeffd$Zde dedged^efd%Zdefd&Zdefd'ZdIdedeefd(ZdIdedeefd)Zdefd*ZdIdedeefd+Z dQdeddee"d2ee"d,eedeedeedeefd-Zd.e fd/Z d`dede d.ed0e d1e f d2ZdNd.ed3eed4eefd5Z dQd.edgeedjeed0ee d1ee d6eed7eefd8ZdNd.e d9ee d:eefd;Zdefd<Zded=e fd>Z dIded=e d?ed@e$ed9eddffdAZded=e dBefdCZded=e d?ed@efdDZɐdIded edeefdEZ dIdedFe deefdGZ dHefdIZ̐dadedJefdKZ͐dLZΐdMZϐdIdNe deefdOZАdHefdPZ dHedQe fdRZҐdIdHedeefdSZdgedjedefdTZԐdUZՐdbdgedjedhefdVZ֐dWZאdXZdefdYZ dcdedde"d2ee"deefdZZdefd[Z dddede$eeefdde"d2ee"fd\Zܐd^dedde"d2e"fd]Z dededeedde"d2e"de f d^Zdefd_Zdede fd`Zde fdaZde fdbZde fdcZdededee"fddZ d ede fdeZde de fdfZde de fdgZ de fdhZde fdiZd ede fdjZdkedledmede$e effdnZdoe de fdpZdoe de fdqZdoe d ede fdrZ de fdsZdte de fduZ de fdvZ de fdwZdxe de fdyZdxe dee fdzZdxe d{e dee fd|Zdxe de fd}Zdle dxe d{e de fd~Z dfdtede$eeefdde"d2ee"deedeede fdZ dgdtede$eeefdeed2ee"deef dZdtefdZdee"deedeeeeffdZ dfdtede$eefdde"d2ee"deedeede fdZ dhdtede$eefd2ee"deefdZ didted2e"de ddee"deedef dZdjdted2e"de ddee"def dZ dkdted2ee"de ddee"def dZde fdZde de fdZ de fdZ dGdee"dee"deedeede f dZde fdZde fdZdede fdZdede fdZdede fdZ dede fdZ de fdZ dedede fdZ dede fdZdede fdZdIdeefdZdIde deede fdZde dede fdZ dGdedgedjeedeeedeedeef dZ de fdZdlde de de fdZdldHe"de de fdZdmdde"d2e"deede fdZd ede fdZ dIdedeede fdZdede de fdZ de de fdZ de fdZ de fdZ dede fdZ de dede fdZdgedjede de de f dZ dnde de de dede f dZ!dodede fdZ"de fd„Z#dede fdÄZ$de ddfdńZ%dpde"de fdƄZ&dlde de fdȄZ' dNdee deede fdʄZ(de de fd˄Z) dqde de de dede f d΄Z*dId eede$e effdτZ+dede fdЄZ,dede fdфZ-de de fdӄZ. dNdeedee de fdՄZ/dedgede fdքZ0dId eede$e effdׄZ1drde de fd؄Z2 dsde d eede$e effdلZ3drde de fdڄZ4defdۄZ5de fd܄Z6de de fd݄Z7de de fdބZ8de dede fd߄Z9de de fdZ:de de fdZ;de dede fdZ dQdeedeedeedeedeedee de fdZ? dNdeedeedede fdZ@d!ede fdZA dIdedede"de deede f dZBdedede fdZCd4ed5edBede fdZDdedBede fdZEde de fdZFde de fdZGdIdeede fdZHde dede fdZIde de de fdZJde dede fdZKde de fdZLde de de de fdZMde de de d ede f dZNde fdZOde fdZPdede fdZQdldede defdZRde de fd ZSd e de fd ZTdwe de fd ZUdIdgedhedwe d eede f dZV dtdeedeedeedde"d2e"de f dZWde de fdZXde de fdZYde de fdZZde de fdZ[ dude dtededde"d2ee"deede fdZ\ dSde de dde"d2e"de f dZ] dvde de dtededededde"d2e"de fdZ^ dvde dtededededde"d2e"de fdZ_d^de dde"d2e"de fdZ`de de fdZade dRede fdZbde dRede fd Zcde dRede fd!Zdde de fd"Zede d ede fd#Zf dede d$eedde"d2e"de f d%Zged&d') dede d$eedde"d2e"de f d(Zh dwde d)e dted*e dededde"d2e"de fd+Zi dxde d,edde"d2e"de f d-Zj dHdgede d6eed.eed/eede f d0Zkd)e d eede fd1Zld)e de fd2Zmd)e dged6ed.ede f d3Znd)e de fd4Zod)e d ede fd5Zpd)e dde d2e de fd6Zqd7e d8ed9e de fd:Zrde fd;Zsde de fd?Zude fd@Zvde fdAZwde fdBZxde fdCZydZdedDe de fdEZzxZ{S(yJiraz Provide permission information for the current user. Reference: https://docs.atlassian.com/software/jira/docs/api/REST/8.5.0/#api/2 urlargskwargscFd|vrd|d<tt| |g|i|y)N api_version2)superr__init__)selfrrr __class__s F/var/www/timesheet/venv/lib/python3.12/site-packages/atlassian/jira.pyr z Jira.__init__s.  &$'F= ! dD"3888NFparamsdataflagstrailingabsolutec #TK|jr|i} tdtt|||||||}|j dg}|D]} | |j ddst |dk(r ytd |j d }| yd}i}d}t d w) a> Used to get the paged data :param url: string: The url to retrieve :param params: dict (default is None): The parameter's :param data: dict (default is None): The data :param flags: string[] (default is None): The flags :param trailing: bool (default is None): If True, a trailing slash is added to the url :param absolute: bool (default is False): If True, the url is used absolute and not relative to the root :return: A generator object for the data elements NTdict)r(r%r&r'r)valuesisLastFrstrnextPagez?``_get_paged`` method is only available for Jira Cloud platform)cloudr rrgetlen ValueError) r!rr%r&r'r(r)responser,valuer"s r# _get_pagedzJira._get_paged#s, ::~$)!)%!#!) * "h3# EK <<%0CK14D 5(,,z":;;   7:^_ _sB%B( permissions project_id project_keyissue_id issue_keyreturnc|jd}d|i}|r||d<|r||d<|r||d<|r||d<|j||S)a Returns a list of permissions indicating which permissions the user has. Details of the user's permissions can be obtained in a global, project, issue or comment context. The user is reported as having a project permission: - in the global context, if the user has the project permission in any project. - for a project, where the project permission is determined using issue data, if the user meets the permission's criteria for any issue in the project. Otherwise, if the user has the project permission in the project. - for an issue, where a project permission is determined using issue data, if the user has the permission in the issue. Otherwise, if the user has the project permission in the project containing the issue. - for a comment, where the user has both the permission to browse the comment and the project permission for the comment's parent issue. Only the BROWSE_PROJECTS permission is supported. If a commentId is provided whose permissions does not equal BROWSE_PROJECTS, a 400 error will be returned. This means that users may be shown as having an issue permission (such as EDIT_ISSUES) in the global context or a project context but may not have the permission for any or all issues. For example, if Reporters have the EDIT_ISSUES permission a user would be shown as having this permission in the global context or the context of a project, because any user can be a reporter. However, if they are not the user who reported the issue queried they would not have EDIT_ISSUES permission for that issue. Global permissions are unaffected by context. This operation can be accessed anonymously. :param permissions: (str) A list of permission keys. This parameter accepts a comma-separated list. (Required) :param project_id: (str) id of project to scope returned permissions for. :param project_key: (str) key of project to scope returned permissions for. :param issue_id: (str) key of the issue to scope returned permissions for. :param issue_key: (str) id of the issue to scope returned permissions for. :return: mypermissionsr7 projectId projectKeyissueIdissueKeyr% resource_urlr1)r!r7r8r9r:r;rr%s r#get_permissionszJira.get_permissions^sfR0.;[-I ",F;  #.F<  (F9  !*F: xxFx++r$cF|jd}|j|S)z Returns all permissions that are present in the Jira instance - Global, Project and the global ones added by plugins :return: All permissions r7rDr!rs r#get_all_permissionszJira.get_all_permissionss"  .xx}r$keypermission_level key_filtercx|jd}i}|r||d<|r||d<|r||d<|j||S)z Returns an application property :param key: str :param permission_level: str :param key_filter: str :return: list or item application-propertiesrJpermissionLevel keyFilterrCrD)r!rJrKrLrr%s r# get_propertyzJira.get_propertysT 89 F5M (8F$ % ",F; xxFx++r$ property_idr5cb|jd}|d|}||d}|j||S)z Modify an application property via PUT. The "value" field present in the PUT will override the existing value. :param property_id: :param value: :return: rN/)idr5r&rEput)r!rRr5base_urlrr&s r# set_propertyzJira.set_propertysB$$%=> !K=)!E2xx$x''r$cF|jd}|j|S)z Returns the properties that are displayed on the "General Configuration > Advanced Settings" page. :return: z(application-properties/advanced-settingsrDrHs r#get_advanced_settingszJira.get_advanced_settingss#  JKxx}r$cN|jd}|j|xsiS)zM Returns all ApplicationRoles in the system :return: applicationrolerDrHs r#get_all_application_roleszJira.get_all_application_roless(  12xx}""r$role_keyc\|jd}|d|}|j|xsiS)zx Returns the ApplicationRole with passed key if it exists :param role_key: str :return: r^rTrD)r!r`rYrs r#get_application_rolezJira.get_application_roles8 $$%67 !H:&xx}""r$issuecz|j|dd}g}|D]}|j|d|dd|S)z Get attachments IDs from jira issue :param issue: str : jira issue key :return: list of integers attachment IDs fields attachmentfilenamerU)rg attachment_id get_issueappend)r!rcr:list_attachments_idrfs r#get_attachments_ids_from_issuez#Jira.get_attachments_ids_from_issuesX >>%(2<@ " pJ  & &Jz4J]ghl]m'n o p""r$rhcT|jd}|d|}|j|S)z Returns the meta-data for an attachment, including the URI of the actual attached file :param attachment_id: int :return: rfrTrDr!rhrYrs r#get_attachmentzJira.get_attachment2 $$\2 !M?+xx}r$pathc>|j|||jS)a9 Downloads all attachments from a Jira issue. :param issue: The issue-key of the Jira issue :param path: Path to directory where attachments will be saved. If None, current working directory will be used. :return: A message indicating the result of the download operation. )rcrrr0)download_attachments_from_issuer0)r!rcrrs r#download_issue_attachmentszJira.download_issue_attachmentss#33%dRVR\R\3]]r$z3.41.20z&Use download_issue_attachments instead)versionreasonr0c |tj}|j|dd}|r|jd|dz}n|jd|dz}|jj |}|d}tj j||}td|jd D} | d k(ry tj j|ry t|d 5} | j|jdddy#1swYyxYw#t$r tdt$r tdt $r} | d} ~ wwxYw)a Downloads all attachments from a Jira issue. :param issue: The issue-key of the Jira issue :param path: Path to directory where attachments will be saved. If None, current working directory will be used. :param cloud: Use True for Jira Cloud, false when using Jira Data Center or Server :return: A message indicating the result of the download operation. NrUrez/secure/issueAttachments/z.zipz/secure/attachmentzip/z_attachments.zipc32K|]}t|ywN)r2).0chunks r# z7Jira.download_attachments_from_issue..#sP5CJPsi z&No attachments found on the Jira issuezFile already existswbz#Attachments downloaded successfullyz>Verify if directory path is correct and/or if directory existszgDirectory found, but there is a problem with saving file to this directory. Check directory permissions)osgetcwdrcr_sessionr1rrjoinsum iter_contentisfileopenwritecontentFileNotFoundErrorPermissionError Exception) r!rcrrr0r:rr4attachment_name file_path file_sizefes r#rtz$Jira.download_attachments_from_issue sG |yy{zz%z5d;Hhh#D D*DDDDD/E E  EcX|jd}|d|}|j|dS)z{ Returns the content for an attachment :param attachment_id: int :return: content as bytes rfz /content/Tnot_json_responserDros r#get_attachment_contentzJira.get_attachment_content5s7 $$\2 )M?3xxtx44r$cT|jd}|d|}|j|S)z Remove an attachment from an issue :param attachment_id: int :return: if success, return None rfrTrEdeleteros r#remove_attachmentzJira.remove_attachment?s3 $$\2 !M?+{{3r$cF|jd}|j|S)z Returns the meta information for an attachments, specifically if they are enabled and the maximum upload size allowed :return: zattachment/metarDrHs r#get_attachment_metazJira.get_attachment_metaIs#  12xx}r$cV|jd}|d|d}|j|S)z Returns the information for an expandable attachment in human-readable format :param attachment_id: int :return: rfrTz /expand/humanrDros r#get_attachment_expand_humanz Jira.get_attachment_expand_humanRs4 $$\2 !M?-8xx}r$cV|jd}|d|d}|j|S)z Returns the information for an expandable attachment in raw format :param attachment_id: int :return: rfrTz /expand/rawrDros r#get_attachment_expand_rawzJira.get_attachment_expand_raw\s4 $$\2 !M?+6xx}r$offsetlimitfilter from_dateto_dateci}|r||d<|r||d<|r||d<|r||d<|r||d<|jd}|j||xsiS)a Returns auditing records filtered using provided parameters :param offset: the number of record from which search starts :param limit: maximum number of returned results (if is limit is <= 0 or > 1000, it will be set do default value: 1000) :param str filter: text query; each record that will be returned must contain the provided text in one of its fields. :param str from_date: timestamp in the past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or after the 'from' timestamp will be provided in response :param str to_date: timestamp in the past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or earlier than the 'to' timestamp will be provided in response :return: rrrfromtoauditing/recordrCrD)r!rrrrrr%rs r#get_audit_recordszJira.get_audit_recordsksp. %F8  #F7O %F8  &F6N "F4L 12xxFx+1r1r$ audit_recordcJ|jd}|j||S)z Store a record in Audit Log :param audit_record: json with compat https://docs.atlassian.com/jira/REST/schema/audit-record# :return: rrVrEpost)r!rrs r#post_audit_recordzJira.post_audit_records(  12yy8aQwZ8IrI8s 99cT|jd}|d|}|j|S)z Request current index from node (the request is processed asynchronously). This method is deprecated as it is Lucene specific and is planned for removal in Jira 11. :return: zcluster/index-snapshotrTrWrs r#request_current_index_from_nodez$Jira.request_current_index_from_nodes3 $$%=> !G9%xx}r$node_idsc4d|i}d}|j||S)z Generate a support zip on targeted nodes of a cluster :param node_ids: list :return: dict representing cluster task created nodeIdsz0/rest/troubleshooting/latest/support-zip/clusterrVr)r!rr&rs r#generate_support_zip_on_nodesz"Jira.generate_support_zip_on_nodess& 8$@yy4y((r$cluster_task_idc.d|}|j|S)zp Check status of support zip creation task :param cluster_task_id: str :return: z8/rest/troubleshooting/latest/support-zip/status/cluster/r1)r!rrs r#check_support_zip_statuszJira.check_support_zip_statuss IHYZxx}r$ file_namecFd|}|j|djS)zt Download created support zip file :param file_name: str :return: bytes of zip file z2/rest/troubleshooting/latest/support-zip/download/T) advanced_mode)r1r)r!rrs r#download_support_zipzJira.download_support_zips* C9+Nxx4x0888r$cF|jd}|j|S)z@ Approves the cluster upgrade. :return: zcluster/zdu/approverrHs r#approve_cluster_zdu_upgradez Jira.approve_cluster_zdu_upgrades#  56yy~r$cF|jd}|j|S)zG Cancels the ongoing cluster upgrade. :return: zcluster/zdu/cancelrrHs r#cancel_cluster_zdu_upgradezJira.cancel_cluster_zdu_upgrade s#  45yy~r$cF|jd}|j|S)z? Retries the cluster upgrade. :return: zcluster/zdu/retryUpgraderrHs r#retry_cluster_zdu_upgradezJira.retry_cluster_zdu_upgrades#  :;yy~r$cF|jd}|j|S)z> Starts the cluster upgrade. :return: zcluster/zdu/startrrHs r#start_cluster_zdu_upgradezJira.start_cluster_zdu_upgrades#  34yy~r$cF|jd}|j|S)zH Get the state of the cluster upgrade. :return: zcluster/zdu/staterDrHs r#get_cluster_zdu_statezJira.get_cluster_zdu_state"s#  34xx}r$cV|jd}|d|d}|j|S)z Get Comments on an Issue. :param issue_id: Issue ID :raises: requests.exceptions.HTTPError :return: rcrT/commentrD)r!r:rYrs r#issue_get_commentszJira.issue_get_comments+s4$$W- !H:X.xx}r$c t|Dcgc]}t|tc}s tddt |i}|j d}|d}|j ||Scc}w)z Get Comments on Multiple Issues :param args: int Issue ID's :raises: requests.exceptions.HTTPError :return: z4Arguments to `issues_get_comments_by_id` must be intidscommentz/listrV)all isinstanceint TypeErrorlistrEr)r!rir&rYrs r#issues_get_comments_by_idzJira.issues_get_comments_by_id6sl51Jq#&56RS StDz"$$Y/ % yy4y(( 6sA) comment_idcZ|jd}|d|d|}|j|S)z Get a single comment :param issue_id: int or str :param comment_id: int :raises: requests.exceptions.HTTPError :return: rcrT /comment/rD)r!r:rrYrs r#issue_get_commentzJira.issue_get_commentDs8$$W- !H:Yzl;xx}r$cV|jd}|d|d}|j|S)z Returns the keys of all properties for the comment identified by the key or by the id. :param comment_id: :return: rrT /propertiesrD)r!rrYrs r#get_comment_properties_keysz Jira.get_comment_properties_keysUs4 $$Y/ !J<{3xx}r$ property_keycZ|jd}|d|d|}|j|S)z Returns the value a property for a comment :param comment_id: int :param property_key: str :return: rrT /properties/rDr!rrrYrs r#get_comment_propertyzJira.get_comment_property_s8$$Y/ !J<|L>Bxx}r$value_propertycf|jd}|d|d|}d|i}|j||S)z Returns the keys of all properties for the comment identified by the key or by the id. :param comment_id: int :param property_key: str :param value_property: object :return: rrTrr5rVrW)r!rrrrYrr&s r#set_comment_propertyzJira.set_comment_propertyjsG$$Y/ !J<|L>B(xx$x''r$cZ|jd}|d|d|}|j|S)z Deletes a property for a comment :param comment_id: int :param property_key: str :return: rrTrrrs r#delete_comment_propertyzJira.delete_comment_propertyws9$$Y/ !J<|L>B{{3r$ component_idcP|jd}|j|d|S)N componentrTrDr!rrYs r#rzJira.components,$$[1xx8*Al^455r$cV|jd}|d|d}|j|S)zs Returns counts of issues related to this component. :param component_id: :return: rrTz/relatedIssueCountsrD)r!rrYrs r#get_component_related_issuesz!Jira.get_component_related_issuess5 $$[1 !L>)<=xx}r$rctjd|d|jd}|d}|j||S)NzCreating component "%s"namerrTrVloginforEr)r!rrYrs r#create_componentzJira.create_componentsD *If,=>$$[1 !nyy9y--r$cX|jd}|d|}|j||S)NrrTrVrW)r!rrrYrs r#update_componentzJira.update_components5$$[1 !L>*xx)x,,r$c|tjd||jd}|j|d|S)NzDeleting component "%s"rrTrrrErrs r#delete_componentzJira.delete_components; *L9$$[1{{hZq788r$leadc^||d}|jd}|j|d||S)N)rU leadUserNamerrTrVrW)r!rr r&rYs r#update_component_leadzJira.update_component_leadsC"D9$$[1xxj, (  r$cF|jd}|j|S)z Returns the information if the optional features in JIRA are enabled or disabled. If the time tracking is enabled, it also returns the detailed information about time tracking configuration. :return: configurationrDrHs r#get_configurations_of_jirazJira.get_configurations_of_jiras" 0xx}r$ option_idcT|jd}|d|}|j|S)z Returns a full representation of the Custom Field Option that has the given id. :param option_id: :return: customFieldOptionrTrD)r!rrYrs r#get_custom_field_optionzJira.get_custom_field_options3 $$%89 !I;'xx}r$searchstartc|jr|jd}n|jd}i}|r||d<|r||d<|r||d<|j||S)z Get custom fields. Evaluated on 7.12 Get fields paginated in cloud :param search: str :param start: long Default: 1 :param limit: int Default: 50 :return: z field/search customFieldsrstartAt maxResultsrCr0rEr1)r!rrrrr%s r#get_custom_fieldszJira.get_custom_fieldssj ::##N3C##N3C %F8   %F9  #(F< xxFx++r$cF|jd}|j|S)z Returns a list of all fields, both System and Custom :return: application/jsonContains a full representation of all visible fields in JSON. fieldrDrHs r#get_all_fieldszJira.get_all_fieldss" (xx}r$rtype search_key descriptionc |jd}|j|jd}|ds td|ds td|r|j|d<|r|j|d<|j|| S) a Creates a custom field with the given name and type This method is primarily for Jira Server/Data Center. For Jira Cloud, the `searcher_key` is not applicable. :param name: str - The name of the custom field (e.g., "My Custom Field"). Cannot be empty. :param type: str, The type of the custom field, which defines its behavior. Example: 'com.atlassian.jira.plugin.system.customfieldtypes:textfield' :param search_key: str, (For Jira Server/DC) The searcher key to make the field searchable. Example: 'com.atlassian.jira.plugin.system.customfieldtypes:textsearcher' :param description: str, An optional description for the custom field. :return: A dictionary representing the created custom field, or None if the API returns no content. Raises HTTPError for API-level errors. API References: - Jira Server: https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/field-createCustomField - Jira Cloud: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-fields/#api-rest-api-2-field-post r)rr!rz0The 'name' for the custom field cannot be empty.r!z0The 'type' for the custom field cannot be empty.r# searcherKeyrV)rEstripr3r)r!rr!r"r#rr&s r#create_custom_fieldzJira.create_custom_fields&( djjl;F|OP PF|OP P "-"3"3"5D  ","2"2"4D yy4y((r$field_id context_idcX|jd|d|dd}|j|S)a0 Gets the current values of a custom field :param field_id: :param context_id: :return: Reference: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-custom-field-options/#api-rest-api-2-field-fieldid-context-contextid-option-get field/ /context//optionrrD)r!r(r)rs r#get_custom_field_option_contextz$Jira.get_custom_field_option_context s>XJi |7 ;  xx}r$optionscdgi}|D]}|djd|d|jd|d|dd}|j|| S) a Adds the values given to the custom field Administrator permission required :param field_id: :param context_id: :param options: List of values to be added :return: Reference: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-custom-field-options/#api-rest-api-2-field-fieldid-context-contextid-option-post r1false)disabledr5r+r,r-r.r/rV)rkrEr)r!r(r)r1r&rrs r#add_custom_field_optionzJira.add_custom_field_optionsv _ FA O " "!#D E FXJi |7 ;  yy4y((r$cxi}|r||d<|r||d<|r||d<|jd}|j||S)a Returns a list of all dashboards, optionally filtering them. :param filter: OPTIONAL: an optional filter that is applied to the list of dashboards. Valid values include "favourite" for returning only favourite dashboards, and "my" for returning dashboards that are owned by the calling user. :param start: the index of the first dashboard to return (0-based). must be 0 or a multiple of maxResults :param limit: a hint as to the maximum number of dashboards to return in each call. Note that the JIRA server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated. Callers should always check the returned maxResults to determine the value that is effectively being used. :return: rrr dashboardrCrD)r!rrrr%rs r#get_dashboardszJira.get_dashboards5sS %F8   %F9  #(F<  ,xxFx++r$ dashboard_idcL|jd|}|j|S)zl Returns a single dashboard :param dashboard_id: Dashboard ID Int :return: z dashboard/rD)r!r9rs r# get_dashboardzJira.get_dashboardNs)*\N ;<xx}r$jql favouritech|||r|nd|rdndd}|jd}|j||S)z :param name: str :param jql: str :param description: str, Optional. Empty string by default :param favourite: bool, Optional. False by default truer3)r<rr#r=rrVr)r!rr<r#r=r&rs r# create_filterzJira.create_filter]sD*5;2#,'   )yy4y((r$ filter_idcd|i}|r||d<|r||d<|r||d<|jd}|d|}|j||S)a: Updates an existing filter. :param filter_id: Filter ID :param name: Filter Name :param jql: Filter JQL :param description: Filter description :param favourite: Indicates if filter is selected as favorite :return: Returns updated filter information rr<r#r=rrTrVrW) r!rBrr<r#r=r&rYrs r# edit_filterzJira.edit_filtermsf"d^ DK "-D   )D $$X. !I;'xx$x''r$cT|jd}|d|}|j|S)z} Returns a full representation of a filter that has the given id. :param filter_id: :return: rrTrDr!rBrYrs r# get_filterzJira.get_filters2 $$X. !I;'xx}r$c d}d|i}t|jD]\}}||vs |j||i|jd}|d|} |j | |S)z :param filter_id: int :param jql: str :param kwargs: dict, Optional (name, description, favourite) :return: )rr#r=r<rrTrV)ritemsupdaterErX) r!rBr<rallowed_fieldsr&kvrYrs r# update_filterzJira.update_filters}>s|( $DAqN" QF# $$$X. !I;'xx$x''r$cT|jd}|d|}|j|S)zd Deletes a filter that has the given id. :param filter_id: :return: rrTrrFs r# delete_filterzJira.delete_filters3 $$X. !I;'{{3r$cV|jd}|d|d}|j|S)z Gets share permissions of a filter. :param filter_id: Filter ID :return: Returns current share permissions of filter rrT /permissionrDrFs r#get_filter_share_permissionsz!Jira.get_filter_share_permissionss4 $$X. !I;k2xx}r$project_role_id groupnameuser_keyvieweditc |jd} | d|d} d|i} |r|| d<|r|| d<|r|| d<|r|| d<|r|| d <|r|| d <|j| | S) a~ Adds share permission for a filter. See the documentation of the sharePermissions. :param filter_id: Filter ID :param type: What type of permission is granted (i.e. user, project) :param project_id: Project ID, relevant for type 'project' and 'projectRole' :param project_role_id: Project role ID, relevant for type 'projectRole' :param groupname: Group name, relevant for type 'group' :param user_key: User key, relevant for type 'user' :param view: Sets view permission :param edit: Sets edit permission :return: Returns updated share permissions rrTrRr!r? projectRoleIdrUuserKeyrWrXrVr) r!rBr!r8rTrUrVrWrXrYrr&s r#add_filter_share_permissionz Jira.add_filter_share_permissions.$$X. !I;k2d^  *D  $3D !  )D  &DO DL DLyy4y((r$ permission_idcZ|jd}|d|d|}|j|S)z Removes share permission :param filter_id: Filter ID :param permission_id: Permission ID to be removed :return: rrTz /permission/r)r!rBr]rYrs r#delete_filter_share_permissionz#Jira.delete_filter_share_permissions9$$X. !I;l=/B{{3r$queryexcludec|jd}i}|r||d<nd|d<|r||d<|r||d<|j||S)a REST endpoint for searching groups in a group picker Returns groups with substrings matching a given query. This is mainly for use with the group picker, so the returned groups contain html to be used as picker suggestions. The groups are also wrapped in a single response object that also contains a header for use in the picker, specifically Showing X of Y matching groups. The number of groups returned is limited by the system property "jira.ajax.autocomplete.limit" The groups will be unique and sorted. :param query: str - Query of searching groups by name. :param exclude: str - Exclude groups from search results. :param limit: int :return: Returned even if no groups match the given substring z groups/pickerr`r?rarrCrD)r!r`rarrr%s r# get_groupszJira.get_groupss[0 #F7O F7O  'F9  #(F< xxFx++r$cR|jd}d|i}|j||S)zu Create a group by given group parameter :param name: str :return: New group params grouprrVr)r!rrr&s r# create_groupzJira.create_group s0(~yy4y((r$ swap_groupctjd||jd}|||d}nd|i}|j||S)a Delete a group by given group parameter If you delete a group and content is restricted to that group, the content will be hidden from all users To prevent this, use this parameter to specify a different group to transfer the restrictions (comments and worklogs only) to :param name: str - name :param swap_group: str - swap group :return: zRemoving group: %s re)rU swapGrouprUrCr )r!rrgrr%s r# remove_groupzJira.remove_groupsP &-(  !#'jAF!4(F{{3v{..r$reinclude_inactive_userscz|jd}i}|r||d<||d<||d<||d<|j||S)a Just wrapping method user group members :param group: :param include_inactive_users: :param start: OPTIONAL: The start point of the collection to return. Default: 0. :param limit: OPTIONAL: The limit of the number of users to return, this may be restricted by fixed system limits. Default by built-in method: 50 :return: z group/memberrUincludeInactiveUsersrrrCrD)r!rerkrrrr%s r#get_all_users_from_groupzJira.get_all_users_from_group(sX/ "'F; )?%&!y$|xxFx++r$username group_name account_idc|jd}d|i}|j}d|vrd|i}nd|i}|j|||S)ay Add given user to a group For Jira DC/Server platform :param username: str :param group_name: str :return: Current state of the group For Jira Cloud platform :param account_id: str (name is no longer available for Jira Cloud platform) :param group_name: str :return: Current state of the group group/userrU atlassian.net accountIdrr%r&)rErr)r!rorprqrr% url_domainr&s r#add_user_to_groupzJira.add_user_to_group=sX  -#Z0XX j (,DH%DyyV$y77r$ctjd|||jd}|j}d|vr||d}n||d}|j ||S)aL Remove given user from a group For Jira DC/Server platform :param username: str :param group_name: str :return: For Jira Cloud platform :param account_id: str (username is no longer available for Jira Cloud platform) :param group_name: str :return: z"Removing user: %s from a group: %srsrt)rUru)rUrorC)rrrErr)r!rorprqrrwr%s r#remove_user_from_groupzJira.remove_user_from_groupVs] 5xL -XX j (#-JGF#-8DF{{3v{..r$c|jd}i}|r||d<|r||d<|r||d<|r||d<|r||d<|j||S)aT Returns a list of active users that match the search string. This resource cannot be accessed anonymously and requires the Browse Users global permission. Given an issue key this resource will provide a list of users that match the search string and have the browse issue permission for the issue provided. :param: username: :param: issueKey: :param: projectKey: :param: startAt: OPTIONAL :param: maxResults: OPTIONAL :return: List of active users who has browser permission for the given project_key or issue_key zuser/viewissue/searchrorBr@rrrCrD)r!ror;r9rrrr%s r#-get_users_with_browse_permission_to_a_projectz2Jira.get_users_with_browse_permission_to_a_projectosn( 78 !)F:  !*F:  #.F<  %F9  #(F< xxFx++r$reexpandcp|jd}|d|d|}i}|r||d<|j||S)NrcrT?fields=r}rCrD)r!rJrer}rYrr%s r#rcz Jira.issuesM$$W- !C51 %F8 xxFx++r$issue_id_or_key propertiesupdate_historyc|jd}|d|}i}|1t|tttfrdj |}||d<|||d<|r||d<t |j|d<|j||S) aP Returns a full representation of the issue for the given issue key By default, all fields are returned in this get-issue resource :param issue_id_or_key: str :param fields: str :param properties: str :param update_history: bool :param expand: str :return: issue rcrT,rerr} updateHistoryrC) rErrtuplesetrr.lowerr1) r!rrerrr}rYrr%s r#rjzJira.get_issues&$$W- !O,-  &4"45&)%F8   !#-F< %F8 "%n"5";";"=xxFx++r$epiccv|jddd}|d|d|}i}|r||d<|j||S) a Given an epic return all child issues By default, all fields are returned in this get-issue resource Cloud Software API :param epic: str :param fields: list of fields, for example: ['priority', 'summary', 'customfield_10007'] :param expand: str: A comma-separated list of the parameters to expand. :returns: Issues within the epic :rtype: list rz rest/agile1.0)api_rootrrTz/issue?fields=r}rCrD)r!rrer}rYrr%s r# epic_issueszJira.epic_issuessW$$VlPU$V !D6x8 %F8 xxFx++r$ issue_listctjd}t}t}|D]*}tj||s|j |,ddj t |d}|j||}|rhdt|jvrM|dD]0} |D])}|| vs|j ||j|+2|j||\}}||fS)zQ :param fields: :param list issue_list: :return: z\w+-\d+zkey in (z, )ry errorMessages) recompilermatchrkrrr<keysremove bulk_issue) r!rrejira_issue_regexmissing_issuesmatched_issue_keysrJr< query_resultmessages r#rzJira.bulk_issues ::j1!V /Cxx(#."))#. /3'9#:;xxFx3 OtL4E4E4G/HH'8 /%/Cg~&--c2"))#./ / ,0??:v+N (L.^++r$projectctdtdi}|r||d<|jd|}|j||S)z This function is deprecated. See https://confluence.atlassian.com/jiracore/createmeta-rest-endpoint-to-be-removed-975040986.html for further details. zmThis function will fail from Jira 9+. Use issue_createmeta_issuetypes or issue_createmeta_fieldtypes instead.r.) stacklevelr}zissue/createmeta?projectKeys=rC)r DeprecationWarningrEr1)r!rr}r%rs r#issue_createmetazJira.issue_createmetasW  V    %F8 "?y IJxxFx++r$cr|jd|d}i}|r||d<|r||d<|j||S)aJ Get create metadata issue types for a project Returns a page of issue type metadata for a specified project. Use the information to populate the requests in Create issue and Create issues. :param project: :param start: default: 0 :param limit: default: 50 :return: issue/createmeta/z /issuetypesrrrCrD)r!rrrrr%s r#issue_createmeta_issuetypesz Jira.issue_createmeta_issuetypessP"3G9K HI  %F9  #(F< xxFx++r$ issue_type_idcv|jd|d|}i}|r||d<|r||d<|j||S)a Get create field metadata for a project and issue type id Returns a page of field metadata for a specified project and issuetype id. Use the information to populate the requests in Create issue and Create issues. This operation can be accessed anonymously. :param project: :param issue_type_id: :param start: default: 0 :param limit: default: 50 :return: rz /issuetypes/rrrCrD)r!rrrrrr%s r#issue_createmeta_fieldtypesz Jira.issue_createmeta_fieldtypessT"3G9L XY  %F9  #(F< xxFx++r$cV|jd}|d|d}|j|S)NrcrTz /editmetarDr!rJrYrs r#issue_editmetazJira.issue_editmeta%s2$$W- !C5 *xx}r$c|jd}i}|r||d<|r||d<|jr|d|d}|j||S|d|d}|j|d|fg S) z Get issue related change log :param issue_key: :param start: start index, usually 0 :param limit: limit of the results, usually 50 :return: rcrrrTz /changelogrCz?expand=changelog changelogry)rEr0r1_get_response_content)r!r;rrrYr%rs r#get_issue_changelogzJira.get_issue_changelog*s$$W-  %F9  #(F< ::Ja {*5C88C8/ /Ja {*;