Projects and their Associated Objects

This section of the documentation covers the representations of various objects related to the Projects API.

Project Objects

class github3.projects.Project(json, session: GitHubSession)

Object representing a single project from the API.

See http://developer.github.com/v3/projects/ for more details.

body: The Markdown formatted text describing the project.

created_at: A datetime representing the date and time when this project was created.

creator: A ShortUser instance representing the user who created this project.

id: The unique identifier for this project on GitHub.

name: The name given to this project.

number: The repository-local identifier of this project.

owner_url: The URL of the resource in the API of the owning resource - either a repository or an organization.

updated_at: A datetime representing the date and time when this project was last updated.

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:: this object’s attributes serialized to a dictionary
Return type:: dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:: this object’s attributes as a JSON string
Return type:: str

column(id)

Get a project column with the given ID.

Parameters:: id (int) – (required), the column ID
Returns:: the desired column in the project
Return type:: ProjectColumn

columns(number=-1, etag=None)

Iterate over the columns in this project.

Parameters:

number (int) – (optional), number of columns to return. Default: -1 returns all available columns.
etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of columns

Return type:

ProjectColumn

create_column(name)

Create a column in this project.

Parameters:: name (str) – (required), name of the column
Returns:: the created project column
Return type:: ProjectColumn

delete()

Delete this project.

Returns:: True if successfully deleted, False otherwise
Return type:: bool

classmethod from_dict(json_dict, session): Return an instance of this class formed from json_dict.

classmethod from_json(json, session): Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns:: A brand new session
Return type:: GitHubSession

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:: int

refresh(conditional: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:: conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:: self

update(name=None, body=None)

Update this project.

Parameters:

name (str) – (optional), new name of the project
body (str) – (optional), new body of the project

Returns:

True if successfully updated, False otherwise

Return type:

bool

class github3.projects.ProjectColumn(json, session: GitHubSession)

Object representing a column in a project.

See http://developer.github.com/v3/projects/columns/

created_at: A datetime object representing the date and time when the column was created.

id: The unique identifier for this column across GitHub.

name: The name given to this column.

project_url: The URL used to retrieve the project that owns this column via the API.

updated_at: A datetime object representing the date and time when the column was last updated.

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:: this object’s attributes serialized to a dictionary
Return type:: dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:: this object’s attributes as a JSON string
Return type:: str

card(id)

Get a project card with the given ID.

Parameters:: id (int) – (required), the card ID
Returns:: the card identified by the provided id
Return type:: ProjectCard

cards(number=-1, etag=None)

Iterate over the cards in this column.

Parameters:

number (int) – (optional), number of cards to return. Default: -1 returns all available cards.
etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of cards

Return type:

ProjectCard

create_card_with_content_id(content_id, content_type)

Create a content card in this project column.

Parameters:

content_id (int) – (required), the ID of the content
content_type (str) – (required), the type of the content

Returns:

the created card

Return type:

ProjectCard

create_card_with_issue(issue)

Create a card in this project column linked with an Issue.

Parameters:: issue (Issue) – (required), an issue with which to link the card. Can also be ShortIssue.
Returns:: the created card
Return type:: ProjectCard

create_card_with_note(note)

Create a note card in this project column.

Parameters:: note (str) – (required), the note content
Returns:: the created card
Return type:: ProjectCard

delete()

Delete this column.

Returns:: True if successful, False otherwise
Return type:: bool

classmethod from_dict(json_dict, session): Return an instance of this class formed from json_dict.

classmethod from_json(json, session): Return an instance of this class formed from json.

move(position)

Move this column.

Parameters:: position (str) – (required), can be one of first, last, or after:<column-id>, where <column-id> is the id value of a column in the same project.
Returns:: True if successful, False otherwise
Return type:: bool

new_session()

Generate a new session.

Returns:: A brand new session
Return type:: GitHubSession

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:: int

refresh(conditional: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:: conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:: self

update(name=None)

Update this column.

Parameters:: name (str) – (optional), name of the column
Returns:: True if successful, False otherwise
Return type:: bool

class github3.projects.ProjectCard(json, session: GitHubSession)

Object representing a “card” on a project.

See http://developer.github.com/v3/projects/cards/

column_url: The URL to retrieve this card’s column via the API.

content_url: The URl to retrieve this card’s body content via the API.

created_at: A datetime object representing the date and time when the column was created.

id: The globally unique identifier for this card.

note: The body of the note attached to this card.

updated_at: A datetime object representing the date and time when the column was last updated.

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:: this object’s attributes serialized to a dictionary
Return type:: dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:: this object’s attributes as a JSON string
Return type:: str

delete()

Delete this card.

Returns:: True if successfully deleted, False otherwise
Return type:: bool

classmethod from_dict(json_dict, session): Return an instance of this class formed from json_dict.

classmethod from_json(json, session): Return an instance of this class formed from json.

move(position, column_id)

Move this card.

Parameters:

position (str) – (required), can be one of top, bottom, or after:<card-id>, where <card-id> is the id value of a card in the same column, or in the new column specified by column_id.
column_id (int) – (required), the id value of a column in the same project.

Returns:

True if successfully moved, False

Return type:

bool

new_session()

Generate a new session.

Returns:: A brand new session
Return type:: GitHubSession

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:: int

refresh(conditional: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:: conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:: self

retrieve_issue_from_content()

Attempt to retrieve an Issue from the content url.

Returns:

The issue that backs up this particular project card if the card has a content_url.

Note

Cards can be created from Issues and Pull Requests. Pull Requests are also technically Issues so this method is always safe to call.

Return type:

Issue

Raises:

CardHasNoContentUrl

retrieve_pull_request_from_content()

Attempt to retrieve an PullRequest from the content url.

Returns:

The pull request that backs this particular project card if the card has a content_url.

Note

Cards can be created from Issues and Pull Requests.

Return type:

Issue

Raises:

CardHasNoContentUrl

update(note=None)

Update this card.

Parameters:: note (str) – (optional), the card’s note content. Only valid for cards without another type of content, so this cannot be specified if the card already has a content_id and content_type.
Returns:: True if successfully updated, False otherwise
Return type:: bool