0
# Project & Component Management
1

2
Project administration including project creation, component management, version control, role assignment, and avatar management. These operations require appropriate administrative permissions in JIRA.
3

4
## Capabilities
5

6
### Project Operations
7

8
Core project management functions for creating, retrieving, and managing JIRA projects.
9

10
```python { .api }
11
def projects(self) -> list[Project]:
12
    """Get all visible projects for the current user."""
13

14
def project(self, id: str) -> Project:
15
    """
16
    Get a specific project by ID or key.
17
    
18
    Parameters:
19
    - id: Project ID or key
20
    
21
    Returns:
22
    Project object
23
    """
24

25
def create_project(
26
    self,
27
    key: str,
28
    name: str = None,
29
    assignee: str = None,
30
    type: str = "Software",
31
    template_name: str = None
32
) -> Project:
33
    """
34
    Create a new project.
35
    
36
    Parameters:
37
    - key: Project key (must be unique)
38
    - name: Project name (defaults to key if not provided)
39
    - assignee: Default assignee username
40
    - type: Project type (Software, Business, Service Desk)
41
    - template_name: Template to use for project creation
42
    
43
    Returns:
44
    Created Project object
45
    """
46

47
def delete_project(self, pid: str) -> None:
48
    """
49
    Delete a project.
50
    
51
    Parameters:
52
    - pid: Project ID or key
53
    """
54
```
55

56
Usage examples:
57
```python
58
# Get all projects
59
projects = jira.projects()
60
for project in projects:
61
    print(f"{project.key}: {project.name}")
62

63
# Get specific project
64
project = jira.project('MYPROJ')
65
print(f"Project: {project.name}")
66
print(f"Lead: {project.lead.displayName}")
67
print(f"Description: {project.description}")
68

69
# Create new project
70
new_project = jira.create_project(
71
    key='NEWPROJ',
72
    name='New Project',
73
    assignee='john.doe',
74
    type='Software'
75
)
76
print(f"Created project: {new_project.key}")
77

78
# Delete project (use with caution!)
79
jira.delete_project('OLDPROJ')
80
```
81

82
### Component Management
83

84
Manage project components for organizing issues within projects.
85

86
```python { .api }
87
def project_components(self, project: str) -> list[dict]:
88
    """Get all components for a project."""
89

90
def component(self, id: str) -> dict:
91
    """Get component by ID."""
92

93
def create_component(
94
    self,
95
    name: str,
96
    project: str,
97
    description: str = None,
98
    leadUserName: str = None,
99
    assigneeType: str = None,
100
    isAssigneeTypeValid: bool = False
101
) -> dict:
102
    """
103
    Create a project component.
104
    
105
    Parameters:
106
    - name: Component name
107
    - project: Project key or ID
108
    - description: Component description
109
    - leadUserName: Component lead username
110
    - assigneeType: How issues are assigned (PROJECT_DEFAULT, COMPONENT_LEAD, etc.)
111
    - isAssigneeTypeValid: Whether assignee type is valid
112
    
113
    Returns:
114
    Created component dictionary
115
    """
116

117
def component_count_related_issues(self, id: str) -> int:
118
    """Get count of issues related to a component."""
119

120
def delete_component(self, id: str) -> None:
121
    """Delete a component."""
122
```
123

124
Usage examples:
125
```python
126
# Get project components
127
components = jira.project_components('PROJ')
128
for component in components:
129
    print(f"{component['name']}: {component['description']}")
130

131
# Create new component
132
new_component = jira.create_component(
133
    name='Frontend',
134
    project='PROJ',
135
    description='Frontend user interface components',
136
    leadUserName='jane.smith',
137
    assigneeType='COMPONENT_LEAD'
138
)
139

140
# Get component details
141
component = jira.component(new_component['id'])
142
issue_count = jira.component_count_related_issues(component['id'])
143
print(f"Component has {issue_count} related issues")
144

145
# Delete component
146
jira.delete_component(component['id'])
147
```
148

149
### Version Management
150

151
Manage project versions for release planning and tracking.
152

153
```python { .api }
154
def project_versions(self, project: str) -> list[dict]:
155
    """Get all versions for a project."""
156

157
def version(self, id: str, expand: str = None) -> dict:
158
    """Get version by ID."""
159

160
def create_version(
161
    self,
162
    name: str,
163
    project: str,
164
    description: str = None,
165
    releaseDate: str = None,
166
    startDate: str = None,
167
    archived: bool = False,
168
    released: bool = False
169
) -> dict:
170
    """
171
    Create a project version.
172
    
173
    Parameters:
174
    - name: Version name
175
    - project: Project key or ID
176
    - description: Version description
177
    - releaseDate: Release date (YYYY-MM-DD format)
178
    - startDate: Start date (YYYY-MM-DD format)
179
    - archived: Whether version is archived
180
    - released: Whether version is released
181
    
182
    Returns:
183
    Created version dictionary
184
    """
185

186
def move_version(self, id: str, after: str = None, position: str = None) -> dict:
187
    """Move a version in the version list."""
188

189
def version_count_related_issues(self, id: str) -> int:
190
    """Count issues related to a version."""
191

192
def version_count_unresolved_issues(self, id: str) -> int:
193
    """Count unresolved issues for a version."""
194
```
195

196
Usage examples:
197
```python
198
# Get project versions
199
versions = jira.project_versions('PROJ')
200
for version in versions:
201
    print(f"{version['name']}: Released={version['released']}")
202

203
# Create new version
204
new_version = jira.create_version(
205
    name='v2.1.0',
206
    project='PROJ',
207
    description='Minor feature release',
208
    releaseDate='2024-03-15'
209
)
210

211
# Get version details with issue counts
212
version = jira.version(new_version['id'])
213
total_issues = jira.version_count_related_issues(version['id'])
214
unresolved_issues = jira.version_count_unresolved_issues(version['id'])
215
print(f"Version {version['name']}: {unresolved_issues}/{total_issues} unresolved")
216

217
# Move version in list
218
jira.move_version(version['id'], position='First')
219
```
220

221
### Project Roles & Permissions
222

223
Manage project roles and user assignments.
224

225
```python { .api }
226
def project_roles(self, project: str) -> dict:
227
    """Get all roles for a project."""
228

229
def project_role(self, project: str, id: str) -> dict:
230
    """Get specific project role."""
231

232
def my_permissions(
233
    self,
234
    projectKey: str = None,
235
    projectId: str = None,
236
    issueKey: str = None,
237
    issueId: str = None
238
) -> dict:
239
    """
240
    Get current user's permissions.
241
    
242
    Parameters:
243
    - projectKey: Project key to check permissions for
244
    - projectId: Project ID to check permissions for
245
    - issueKey: Issue key to check permissions for
246
    - issueId: Issue ID to check permissions for
247
    
248
    Returns:
249
    Permissions dictionary
250
    """
251
```
252

253
Usage examples:
254
```python
255
# Get project roles
256
roles = jira.project_roles('PROJ')
257
for role_name, role_url in roles.items():
258
    print(f"Role: {role_name}")
259

260
# Get specific role details
261
developer_role = jira.project_role('PROJ', '10000')
262
print(f"Developers: {[user['displayName'] for user in developer_role['actors']]}")
263

264
# Check permissions
265
permissions = jira.my_permissions(projectKey='PROJ')
266
if permissions['permissions']['CREATE_ISSUES']['havePermission']:
267
    print("Can create issues in this project")
268
```
269

270
### Project Avatars
271

272
Manage project avatar images.
273

274
```python { .api }
275
def project_avatars(self, project: str) -> dict:
276
    """Get available avatars for a project."""
277

278
def create_temp_project_avatar(
279
    self,
280
    project: str,
281
    filename: str,
282
    size: int,
283
    avatar_img,
284
    contentType: str = None,
285
    auto_confirm: bool = False
286
) -> dict:
287
    """Create temporary project avatar."""
288

289
def confirm_project_avatar(self, project: str, cropping_properties: dict) -> dict:
290
    """Confirm and crop project avatar."""
291

292
def set_project_avatar(self, project: str, avatar: str) -> None:
293
    """Set project avatar."""
294

295
def delete_project_avatar(self, project: str, avatar: str) -> None:
296
    """Delete project avatar."""
297
```
298

299
Usage examples:
300
```python
301
# Get project avatars
302
avatars = jira.project_avatars('PROJ')
303
print(f"Available avatars: {len(avatars['system']) + len(avatars['custom'])}")
304

305
# Upload and set new avatar
306
with open('project_logo.png', 'rb') as avatar_file:
307
    temp_avatar = jira.create_temp_project_avatar(
308
        project='PROJ',
309
        filename='project_logo.png',
310
        size=avatar_file.tell(),
311
        avatar_img=avatar_file,
312
        contentType='image/png'
313
    )
314

315
# Confirm avatar with cropping
316
cropping = {
317
    'cropperOffsetX': 0,
318
    'cropperOffsetY': 0,
319
    'cropperWidth': 120,
320
    'cropperHeight': 120
321
}
322
confirmed_avatar = jira.confirm_project_avatar('PROJ', cropping)
323
```
324

325
## Project Types
326

327
Common project types available in JIRA:
328

329
- **Software**: For software development projects with agile features
330
- **Business**: For general business projects and task management
331
- **Service Desk**: For IT service management and customer support
332

333
## Component Assignee Types
334

335
Available assignee types for components:
336

337
- **PROJECT_DEFAULT**: Use project default assignee
338
- **COMPONENT_LEAD**: Assign to component lead
339
- **PROJECT_LEAD**: Assign to project lead
340
- **UNASSIGNED**: Leave unassigned
341

342
## Permission Examples
343

344
Common permissions you can check:
345

346
```python
347
permissions = jira.my_permissions(projectKey='PROJ')
348

349
# Check specific permissions
350
can_create = permissions['permissions']['CREATE_ISSUES']['havePermission']
351
can_delete = permissions['permissions']['DELETE_ISSUES']['havePermission']
352
can_admin = permissions['permissions']['ADMINISTER_PROJECTS']['havePermission']
353

354
print(f"Create: {can_create}, Delete: {can_delete}, Admin: {can_admin}")
355
```