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