gitcode_api.resources.account

Classes for resource groups: OAuth, organizations, search, and users.

class AsyncOAuthResource(client: AsyncAPIClient)

Bases: AsyncResource, AbstractOAuthResource

Asynchronous helpers for GitCode OAuth flows.

build_authorize_url matches OAuthResource exactly. Token helpers mirror OAuthResource.exchange_token() and OAuthResource.refresh_token() (see docs/rest_api/oauth).

Bind the resource to an asynchronous API client.

build_authorize_url(*, client_id: str, redirect_uri: str, scope: str | None = None, state: str | None = None, response_type: str = 'code') → str

Build the GitCode OAuth authorization URL.

Parameters:

client_id – OAuth application client ID.
redirect_uri – Registered redirect URI.
scope – Optional OAuth scopes.
state – Optional CSRF protection value.
response_type – OAuth response type, defaults to "code".

Returns:

Browser URL for the authorization step.

async exchange_token(*, code: str, client_id: str, client_secret: str) → OAuthToken

Exchange an authorization code for an OAuth token.

Parameters:

code – Authorization code returned by GitCode.
client_id – OAuth application client ID.
client_secret – OAuth application client secret.

Returns:

OAuth access token payload.

async refresh_token(*, refresh_token: str) → OAuthToken

Refresh an OAuth token.

Parameters:: refresh_token – Refresh token previously issued by GitCode.
Returns:: Refreshed OAuth token payload.

class AsyncOrgsResource(client: AsyncAPIClient)

Bases: AsyncResource, AbstractOrgsResource

Asynchronous organization and enterprise endpoints.

Mirrors OrgsResource; see that class for parameters (docs/rest_api/orgs).

Bind the resource to an asynchronous API client.

async list_for_user(*, username: str, page: int | None = None, per_page: int | None = None) → List[OrganizationSummary]

List organizations for a user.

Parameters:

username – GitCode username or login.
page – Page number.
per_page – Page size.

Returns:

Organizations the user belongs to.

async list_authenticated(*, page: int | None = None, per_page: int | None = None, admin: bool | None = None) → List[OrganizationSummary]

List organizations for the authenticated user.

Parameters:

page – Page number.
per_page – Page size.
admin – Optional admin-only filter.

Returns:

Organizations visible to the authorized user.

async get_member(*, org: str, username: str) → OrganizationMembership

Get an organization member profile.

Parameters:

org – Organization path or login.
username – Member username or login.

Returns:

Organization membership details.

async get(*, org: str) → Organization

Get an organization.

Parameters:: org – Organization path or login.
Returns:: Organization details.

async list_repos(*, org: str, type: str | None = None, page: int | None = None, per_page: int | None = None) → List[Repository]

List repositories for an organization.

Parameters:

org – Organization path or login.
type – Repository type filter such as all, public, or private.
page – Page number.
per_page – Page size.

Returns:

Matching repositories.

async create_repo(*, org: str, name: str, **payload) → Repository

Create an organization repository.

Additional payload fields match the organization repository creation endpoint, such as description, homepage, private, public, auto_init, and default_branch.

Parameters:

org – Organization path or login.
name – Repository name.
payload – Additional repository creation fields.

Returns:

Created repository metadata.

async get_enterprise_member(*, enterprise: str, username: str) → EnterpriseMember

Get a member profile for an enterprise.

Parameters:

enterprise – Enterprise path or login.
username – Member username or login.

Returns:

Enterprise membership details.

async get_membership(*, org: str) → OrganizationMembership

Get the authenticated user’s membership in an organization.

Parameters:: org – Organization path or login.
Returns:: Membership details for the current user.

async list_members(*, org: str, page: int | None = None, per_page: int | None = None, role: str | None = None) → List[User]

List members of an organization.

Parameters:

org – Organization path or login.
page – Page number.
per_page – Page size.
role – Optional role filter such as all, admin, or member.

Returns:

Organization members.

async list_enterprise_members(*, enterprise: str, page: int | None = None, per_page: int | None = None, role: str | None = None) → List[EnterpriseMember]

List members of an enterprise.

Parameters:

enterprise – Enterprise path or login.
page – Page number.
per_page – Page size.
role – Optional role filter.

Returns:

Enterprise members.

async remove_member(*, org: str, username: str) → EmptyResponse

Remove a member from an organization.

Parameters:

org – Organization path or login.
username – Member username or login.

Returns:

API response payload, if any.

async list_followers(*, owner: str, page: int | None = None, per_page: int | None = None) → List[User]

List followers of an organization.

Parameters:

owner – Organization path.
page – Page number.
per_page – Page size.

Returns:

Followers of the organization.

async get_issue_extend_settings(*, org: str) → List[APIObject]

Get extended issue type and status settings for an organization.

Parameters:: org – Organization path or login.
Returns:: Extended issue configuration entries.

async invite_member(*, org: str, username: str, permission: str | None = None, role_id: str | None = None) → User

Invite a user to an organization.

Parameters:

org – Organization path or login.
username – Member username or login.
permission – Permission level such as pull, push, or admin.
role_id – Custom role identifier when using a customized permission.

Returns:

Invited user information with permissions.

async update_enterprise_member(*, enterprise: str, username: str, role: str) → EnterpriseMember

Update the role of an enterprise member.

Parameters:

enterprise – Enterprise path or login.
username – Member username or login.
role – Enterprise role such as viewer, developer, or admin.

Returns:

Updated enterprise membership.

async update(*, org: str, **payload) → Organization

Update organization metadata.

Parameters:

org – Organization path or login.
payload – Updatable fields such as name, email, or description.

Returns:

Updated organization details.

async leave(*, org: str) → None

Leave an organization as the authenticated user.

Parameters:: org – Organization path or login.

class AsyncSearchResource(client: AsyncAPIClient)

Bases: AsyncResource, AbstractSearchResource

Asynchronous search endpoints.

Query parameters match SearchResource (page, per_page, sort, order, etc.); see docs/rest_api/search and the synchronous methods for field meanings.

Bind the resource to an asynchronous API client.

async users(*, q: str, page: int | None = None, per_page: int | None = None, sort: str | None = None, order: str | None = None) → List[SearchUser]

Search users.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field such as joined_at.
order – Sort order, usually asc or desc.

Returns:

Matching user search results.

Search issues.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field.
order – Sort order, usually asc or desc.
repo – Optional repository path filter.
state – Optional issue state filter.

Returns:

Matching issue search results.

Search repositories.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field such as stars_count.
order – Sort order, usually asc or desc.
owner – Optional owner path filter.
fork – Optional fork visibility filter.
language – Optional programming language filter.

Returns:

Matching repository search results.

class AsyncUsersResource(client: AsyncAPIClient)

Bases: AsyncResource, AbstractUsersResource

Asynchronous user and account endpoints.

Mirrors UsersResource; see that class for full parameter descriptions (docs/rest_api/users and related guides).

Bind the resource to an asynchronous API client.

async get(*, username: str) → User

Get a user profile.

Parameters:: username – GitCode username or login.
Returns:: User profile details.

async me() → User

Get the profile of the authenticated user.

Returns:: Authorized user profile.

async list_emails() → List[Email]

List email addresses for the authenticated user.

Returns:: Email records associated with the current account.

async list_events(*, username: str, year: str | None = None, next: str | None = None) → UserEventsResponse

List activity events for a user.

Parameters:

username – GitCode username or login (path segment, see User API).
year – Optional start year filter (query year, e.g. 2024 per documentation).
next – Optional end date / pagination cursor (query next; often an ISO timestamp from a prior page).

Returns:

Event payload grouped by date.

async list_repos(*, username: str, **params) → List[Repository]

List public repositories owned by a user.

Supported filters follow the user repository API documentation, such as type, sort, direction, page, and per_page.

Parameters:

username – GitCode username or login.
params – Query parameters accepted by the REST endpoint.

Returns:

Matching repositories.

async create_key(*, key: str, title: str) → PublicKey

Add a public SSH key for the authenticated user.

Parameters:

key – Public key material.
title – Human-readable key name.

Returns:

Created key metadata.

async list_keys(*, page: int | None = None, per_page: int | None = None) → List[APIObject]

List public SSH keys for the authenticated user.

Parameters:

page – Page number.
per_page – Page size.

Returns:

Public key records.

async delete_key(*, key_id: int | str) → None

Delete a public SSH key.

Parameters:: key_id – Public key identifier.

async get_key(*, key_id: int | str) → PublicKey

Get a single public SSH key.

Parameters:: key_id – Public key identifier.
Returns:: Public key metadata.

async get_namespace(*, path: str) → Namespace

Resolve namespace information for the authenticated user.

Parameters:: path – Namespace path to look up.
Returns:: Namespace details.

async list_starred(*, sort: str | None = None, direction: str | None = None, page: int | None = None, per_page: int | None = None) → List[Repository]

List repositories starred by the authenticated user.

Parameters:

sort – Sort field such as created or updated.
direction – Sort direction, usually asc or desc.
page – Page number.
per_page – Page size.

Returns:

Starred repositories.

class OAuthResource(client: SyncAPIClient)

Bases: SyncResource, AbstractOAuthResource

Helpers for GitCode OAuth URLs and token exchange.

Bind the resource to a synchronous API client.

build_authorize_url(*, client_id: str, redirect_uri: str, scope: str | None = None, state: str | None = None, response_type: str = 'code') → str

Build the GitCode OAuth authorization URL.

Parameters:

client_id – OAuth application client ID.
redirect_uri – Registered redirect URI.
scope – Optional OAuth scopes.
state – Optional CSRF protection value.
response_type – OAuth response type, defaults to "code".

Returns:

Browser URL for the authorization step.

exchange_token(*, code: str, client_id: str, client_secret: str) → OAuthToken

Exchange an authorization code for an OAuth token.

Parameters:

code – Authorization code returned by GitCode.
client_id – OAuth application client ID.
client_secret – OAuth application client secret.

Returns:

OAuth access token payload.

refresh_token(*, refresh_token: str) → OAuthToken

Refresh an OAuth token.

Parameters:: refresh_token – Refresh token previously issued by GitCode.
Returns:: Refreshed OAuth token payload.

class OrgsResource(client: SyncAPIClient)

Bases: SyncResource, AbstractOrgsResource

Synchronous organization and enterprise endpoints.

Bind the resource to a synchronous API client.

list_for_user(*, username: str, page: int | None = None, per_page: int | None = None) → List[OrganizationSummary]

List organizations for a user.

Parameters:

username – GitCode username or login.
page – Page number.
per_page – Page size.

Returns:

Organizations the user belongs to.

list_authenticated(*, page: int | None = None, per_page: int | None = None, admin: bool | None = None) → List[OrganizationSummary]

List organizations for the authenticated user.

Parameters:

page – Page number.
per_page – Page size.
admin – Optional admin-only filter.

Returns:

Organizations visible to the authorized user.

get_member(*, org: str, username: str) → OrganizationMembership

Get an organization member profile.

Parameters:

org – Organization path or login.
username – Member username or login.

Returns:

Organization membership details.

get(*, org: str) → Organization

Get an organization.

Parameters:: org – Organization path or login.
Returns:: Organization details.

list_repos(*, org: str, type: str | None = None, page: int | None = None, per_page: int | None = None) → List[Repository]

List repositories for an organization.

Parameters:

org – Organization path or login.
type – Repository type filter such as all, public, or private.
page – Page number.
per_page – Page size.

Returns:

Matching repositories.

create_repo(*, org: str, name: str, **payload) → Repository

Create an organization repository.

Additional payload fields match the organization repository creation endpoint, such as description, homepage, private, public, auto_init, and default_branch.

Parameters:

org – Organization path or login.
name – Repository name.
payload – Additional repository creation fields.

Returns:

Created repository metadata.

get_enterprise_member(*, enterprise: str, username: str) → EnterpriseMember

Get a member profile for an enterprise.

Parameters:

enterprise – Enterprise path or login.
username – Member username or login.

Returns:

Enterprise membership details.

get_membership(*, org: str) → OrganizationMembership

Get the authenticated user’s membership in an organization.

Parameters:: org – Organization path or login.
Returns:: Membership details for the current user.

list_members(*, org: str, page: int | None = None, per_page: int | None = None, role: str | None = None) → List[User]

List members of an organization.

Parameters:

org – Organization path or login.
page – Page number.
per_page – Page size.
role – Optional role filter such as all, admin, or member.

Returns:

Organization members.

list_enterprise_members(*, enterprise: str, page: int | None = None, per_page: int | None = None, role: str | None = None) → List[EnterpriseMember]

List members of an enterprise.

Parameters:

enterprise – Enterprise path or login.
page – Page number.
per_page – Page size.
role – Optional role filter.

Returns:

Enterprise members.

remove_member(*, org: str, username: str) → EmptyResponse

Remove a member from an organization.

Parameters:

org – Organization path or login.
username – Member username or login.

Returns:

API response payload, if any.

list_followers(*, owner: str, page: int | None = None, per_page: int | None = None) → List[User]

List followers of an organization.

Parameters:

owner – Organization path.
page – Page number.
per_page – Page size.

Returns:

Followers of the organization.

get_issue_extend_settings(*, org: str) → List[APIObject]

Get extended issue type and status settings for an organization.

Parameters:: org – Organization path or login.
Returns:: Extended issue configuration entries.

invite_member(*, org: str, username: str, permission: str | None = None, role_id: str | None = None) → User

Invite a user to an organization.

Parameters:

org – Organization path or login.
username – Member username or login.
permission – Permission level such as pull, push, or admin.
role_id – Custom role identifier when using a customized permission.

Returns:

Invited user information with permissions.

update_enterprise_member(*, enterprise: str, username: str, role: str) → EnterpriseMember

Update the role of an enterprise member.

Parameters:

enterprise – Enterprise path or login.
username – Member username or login.
role – Enterprise role such as viewer, developer, or admin.

Returns:

Updated enterprise membership.

update(*, org: str, **payload) → Organization

Update organization metadata.

Parameters:

org – Organization path or login.
payload – Updatable fields such as name, email, or description.

Returns:

Updated organization details.

leave(*, org: str) → None

Leave an organization as the authenticated user.

Parameters:: org – Organization path or login.

class SearchResource(client: SyncAPIClient)

Bases: SyncResource, AbstractSearchResource

Synchronous search endpoints.

Bind the resource to a synchronous API client.

users(*, q: str, page: int | None = None, per_page: int | None = None, sort: str | None = None, order: str | None = None) → List[SearchUser]

Search users.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field such as joined_at.
order – Sort order, usually asc or desc.

Returns:

Matching user search results.

Search issues.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field.
order – Sort order, usually asc or desc.
repo – Optional repository path filter.
state – Optional issue state filter.

Returns:

Matching issue search results.

Search repositories.

Parameters:

q – Search keywords.
page – Page number.
per_page – Page size.
sort – Optional sort field such as stars_count.
order – Sort order, usually asc or desc.
owner – Optional owner path filter.
fork – Optional fork visibility filter.
language – Optional programming language filter.

Returns:

Matching repository search results.

class UsersResource(client: SyncAPIClient)

Bases: SyncResource, AbstractUsersResource

Synchronous user and account endpoints.

Bind the resource to a synchronous API client.

get(*, username: str) → User

Get a user profile.

Parameters:: username – GitCode username or login.
Returns:: User profile details.

me() → User

Get the profile of the authenticated user.

Returns:: Authorized user profile.

list_emails() → List[Email]

List email addresses for the authenticated user.

Returns:: Email records associated with the current account.

list_events(*, username: str, year: str | None = None, next: str | None = None) → UserEventsResponse

List activity events for a user.

Parameters:

username – GitCode username or login (path segment, see User API).
year – Optional start year filter (query year, e.g. 2024 per documentation).
next – Optional end date / pagination cursor (query next; often an ISO timestamp from a prior page).

Returns:

Event payload grouped by date.

list_repos(*, username: str, **params) → List[Repository]

List public repositories owned by a user.

Supported filters follow the user repository API documentation, such as type, sort, direction, page, and per_page.

Parameters:

username – GitCode username or login.
params – Query parameters accepted by the REST endpoint.

Returns:

Matching repositories.

create_key(*, key: str, title: str) → PublicKey

Add a public SSH key for the authenticated user.

Parameters:

key – Public key material.
title – Human-readable key name.

Returns:

Created key metadata.

list_keys(*, page: int | None = None, per_page: int | None = None) → List[APIObject]

List public SSH keys for the authenticated user.

Parameters:

page – Page number.
per_page – Page size.

Returns:

Public key records.

delete_key(*, key_id: int | str) → None

Delete a public SSH key.

Parameters:: key_id – Public key identifier.

get_key(*, key_id: int | str) → PublicKey

Get a single public SSH key.

Parameters:: key_id – Public key identifier.
Returns:: Public key metadata.

get_namespace(*, path: str) → Namespace

Resolve namespace information for the authenticated user.

Parameters:: path – Namespace path to look up.
Returns:: Namespace details.

list_starred(*, sort: str | None = None, direction: str | None = None, page: int | None = None, per_page: int | None = None) → List[Repository]

List repositories starred by the authenticated user.

Parameters:

sort – Sort field such as created or updated.
direction – Sort direction, usually asc or desc.
page – Page number.
per_page – Page size.

Returns:

Starred repositories.