No project description provided
Project description
ProjectV2 Client
This is an in-progress client to use the ProjectV2 functionality through the GitHub GraphQL API.
Setup
- Install the
projectv2
module:pip3 install github-projectv2
- Create a
.env
file in the root containing a value forGITHUB_API_TOKEN
(this will be loaded usingpython-dotenv
) - Use the
requirements.txt
file to ensure you have all of the dependencies you need. - Enjoy!
NOTE: You can use an actual environment variable instead of the .env
approach, setting the same GITHUB_API_TOKEN
value
Example Usage
from projectv2.project import Project
project = Project()
project.get('myorg', '1234')
print(project.title)
# Find the field with the name "Test Field 1"
found = None
for field in project.fields:
if field.name == "Test Field 1":
found = field
if found is None:
raise Exception("Field not found")
items = project.get_items('myorg')
print(items)
# Look on the project fields and find the one with the name "Test Field 1" and get its options
# Then, find the option with the name "Option 1" and get its id
for option in found.options:
if option.name == "test3":
newOption = option
for item in items:
result = item.update_field_value(project, field, newOption)
print(result)
Modules
Project
The Project
module is used to get the information about a project. It results in an instance with the following properties:
title
(string)description
(string)id
(string): internal ID of project recordnumber
(integer): public-facing ID number of projectfields
(list): Set of fields in the project, default and customitems
(list): Set of "items" in the project, usually issue instancesorg
(string): Name of the organization the project belongs tocreatedAt
(datetime): Date/time of project creationclosedAt
(datetime): Date/time when project was closedclosed
(boolean): The open/closed state of the projectshortDescription
(string): Short description of the projectpublic
(boolean): Visibility for the project (public=True
, private=False
)readme
(string): Full readme for the projecturl
(string): Full public-facing URL location of the project
NOTE: When the get
method is called on the Project
, the get_fields
method will automatically be called to populate the fields
property with instances of the Field
class.
Methods
get(org, projectNumber)
: Get a project by organization name and public-facing project number
Where:
org
(string): the name of the organizationprojectNumber
(string): the public-facing ID for the project
get_fields(org)
: Get the fields for a project given the organization name and public-facing project number
Where:
org
is the name of the organization (optional)
get_items(args)
: Get the items currently in the project (issues)
Where args
are one or more named variables:
org
(string) is the name of the organizationoptions
(dict) are options for the query (see "Query Options" section below) Returns:- A set of
Item
object types
get_views(args)
: Get the current list of views for the project
Where args
are one or more named variables:
org
(string): optional name of the organizationoptions
(dict) are options for the query (see "Query Options" section below) Returns:- A set of
View
object types
create(data)
: Create a new project
Where:
data
(list): Data to use in the creation of the project (required values:title
,ownerId
) Returns:- A
Project
instance with the new data set
remove_item(item)
: Removes an item from a project
Where:
item
must be a record as fetched byget_items
, not from a call toItem.get
Returns:- The internal ID of the deleted item
add_item(item)
: Adds an item/issue to a project
Where:
item
is a record as fetched byItem.get
or from the list fromProject.get_items
Returns:- The internal ID of the item that was added
save()
: Saves the current state of the project record (fields saved are title, shortDescription, readme, closed)
Returns:
- The current instance, a
Project
with the updated information
NOTE: the get_fields
and get_items
require that the project is fetched using get
first and will throw an error otherwise.
Item
The Item
module is used to represent an item in a project (an issue record). It results in an instance with the following properties:
id
(string): internal ID of the item recordtype
(string): type of item (ex:ISSUE
)created
(string): A date/time of when the item was createdassignees
(list): A set ofUser
instancestitle
(string): Title of the item (issue)number
(string): The public-facing number of the itemupdatedAt
(string): A date/time of when the item was last updatedurl
(string): The public-facing URLbody
(string): Unrendered body contentclosed
(boolean): Closed/not closed stateclosedAt
(string): A date/time of when the issue was closedauthor
(list): A set ofUser
instanceslabels
(list): A set ofLabel
instancesprojectNodeId
(string): The internal ID of the item (used when relating to a project, otherwiseNone
)trackedIssues
(list): A set ofItem
instancestrackedInIssues
(list): A set ofItem
instances
Methods
update_field_value(project, field, input)
: Update a single select field to a new value
Where:
project
= aProject
instancefield
= aField
instance representing the field to update the value onoption
= Either an anOption
instance representing the new value or a string value
get(org, repo, itemId)
Where:
org
(string): the name of the organizationrepo
(string): the name of the repositoryitemId
(string): the ID number of the item
clear_field_value(project, field)
Where:
project
: aProject
instancefield
: aField
instance for the field to clear (a result of the objects loaded from aProject.get_fields()
method call)
create(repository, data)
Where:
repository
: aRepository
instancedata
: a data set containing:assigneeIds
,body
,title
(optional:labelIds
,milestoneId
)
Option
The Option
module is used to represent an option on a single-select field. It results in an instance with the following properties:
id
(string): internal ID of the option recordname
(string): the name of the option (this is the option's value)
Field
The Field
module is used to represent a field in the project. It results in an instance with the following properties:
id
(string): internal ID of the field recordname
(string): name of the fielddataType
(string): type of field (Ex:TEXT
orSINGLE_SELECT
)options
(list): when thedataType
isSINGLE_SELECT
the options array will be populated with the options records as instances ofOption
Label
The Label
module is used to represent a label on an item. It results in an instance with the following properties:
id
(string): internal ID of the label recordname
(string): name of the labeldescription
(string): description of the label
User
The User
module is used to represent a user in the system. It results in an instance with the following properties:
id
(string): internal ID of the user recordemail
(string): email address of the userlogin
(string): login/username of the username
(string): user's name
Milestone
The Milestone
module is used to represent a milestone in the system. It results in an instance with the following properties:
id
(string): internal ID of the milestone recorddescription
(string): description of the milestonenumber
(integer): public-facing IDtitle
(string): title of the milestonestate
(string): open/closed statusdueOn
(string): datetime string of when the milestone is
Methods
get(org)
Where:
org
(string): the name of the organization
Repository
The Repository
module is used to represent a repository in the system. It results in an instance with the following properties:
id
(string): internal ID of the repository recordname
(string): name of the repositorydescription
(string): repository descriptionisPrivate
(boolean): public/private statusisArchived
(boolean): archived/not archivedisDisabled
(boolean): disabled/not disabledisFork
(boolean): is a fork/not a forkisLocked
(boolean): is locked/not lockedisMirror
(boolean): is a mirror/not a mirrorisTemplate
(boolean): is a template/not a template
Methods
get(org, name)
Where:
org
(string): organization namename
(string): repository name
get_milestones()
NOTE: get_milestones
requires that get()
is called first
Organization
The Organization
module is used to represent an organization in the system. It results in an instance with the following properties:
id
(string): internal ID of the organization recordname
(string): name of the organization (ex:GitHub
)login
(string): the login of the organization (ex:github
)description
(string): the description of the organizationcreatedAt
(string): datetime stringlocation
(string): location value of the organizationurl
(string): external URL locationrepositories
(list): a list of all repositories in the organization (loads asRepository objects
)
NOTE: Repositories are not loaded by default. get_repositories
must be called to load them. The method will also return the repository list.
Methods
get(login)
Where:
login
(string) the name of the organization Returns:- A single object of type
Organization
get_repositories(login)
Where:
login
(string): the name of the organization (name
is optional, but if not setget
must be called first) Returns:- A set of
Repository
class objects populated with repository data
Search
The Search
module is used to make searches using the search()
method on the GraphQL API using a format similar to those used in the search on the website.
- No properties defined
Methods
issues
Where:
filter
(string): the search filter string Returns:- Set of
Item
class objects populated with matching issue data
View
The View
module represents a view in the project (a tab). It results in an instance with the following properties:
id
(string): internal ID of the viewnumber
(string): the public ID of the viewsortBy
(array): populated when a view is sorted (contains:field.name
,field.id
(internal),field.dataType
,direction
)groupBy
(array): populated when a view is grouped (contains:id
(internal),name
)layout
(string): Layout of the view (ex:TABLE_LAYOUT
orBOARD_LAYOUT
)
Resource: https://mathspp.com/blog/how-to-create-a-python-package-in-2022
Query Options
In some methods (such as project.get_items
) use can used named arguments to configure the requests made to the API (see method definitions above to determine which support the options
named variable)
Supported options:
includeTrackedInIssues
: Includes information about the other item(s) the current item is tracked in (Values:True
/False
)includeTrackedIssues
: Include information about the item(s) being tracked by this item (Values:True
/False
)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for github_projectv2-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cf9ad272f745c1df55ff0d99713ae960fc42f5636c943352249ba41eed73a542 |
|
MD5 | 52cde5d15f4048bda1e1bd18ebb26196 |
|
BLAKE2b-256 | d86011f53b581b1bb766576470f6c84ba82ed5ddfa93ef9c456c436b5f424691 |