tessl/pypi-google-cloud-talent

Google Cloud Talent API client library for job search and talent management

—

Pending

Overview

Eval results

Files

Company Management

Name: tessl/pypi-google-cloud-talent
Author: tessl

Company entity management for organizations that post jobs, including company profiles, metadata, and hierarchical organization management with support for multi-company scenarios. Companies serve as the container for job postings and provide branding and organizational context.

Capabilities

Company Creation

Creates new company entities with comprehensive profile information including display name, external identifiers, size classification, and contact details.

def create_company(self, parent: str, company: Company) -> Company:
    """
    Creates a new company entity.

    Parameters:
    - parent (str): Tenant resource name where company will be created
    - company (Company): Company object with required fields (display_name, external_id)

    Returns:
    Company: Created company with generated resource name

    Raises:
    - InvalidArgument: Missing required fields or invalid values
    - AlreadyExists: Company with same external_id already exists
    - PermissionDenied: Insufficient permissions to create company
    """

Usage Example:

from google.cloud.talent import CompanyServiceClient, Company, CompanySize

client = CompanyServiceClient()

company = Company(
    display_name="Acme Corporation",
    external_id="acme-corp-001",
    size=CompanySize.BIG,
    headquarters_address="123 Business Ave, San Francisco, CA 94105",
    website_uri="https://www.acme.com",
    career_site_uri="https://careers.acme.com",
    image_uri="https://www.acme.com/logo.png",
    eeo_text="Acme Corporation is an equal opportunity employer committed to diversity and inclusion."
)

created_company = client.create_company(
    parent="projects/my-project/tenants/my-tenant",
    company=company
)

print(f"Created company: {created_company.name}")

Company Retrieval

Retrieves individual company profiles by resource name with complete company information and metadata.

def get_company(self, name: str) -> Company:
    """
    Retrieves a company by its resource name.

    Parameters:
    - name (str): Full company resource name

    Returns:
    Company: Complete company object with all fields

    Raises:
    - NotFound: Company does not exist
    - PermissionDenied: Insufficient permissions to view company
    """

Usage Example:

company = client.get_company(
    name="projects/my-project/tenants/my-tenant/companies/company-123"
)

print(f"Company: {company.display_name}")
print(f"Size: {company.size}")
print(f"Website: {company.website_uri}")

Company Updates

Updates existing company profiles with field-level control using update masks to specify which company attributes should be modified.

def update_company(self, company: Company, update_mask: FieldMask = None) -> Company:
    """
    Updates an existing company profile.

    Parameters:
    - company (Company): Company object with updated values and resource name
    - update_mask (FieldMask): Specifies which fields to update

    Returns:
    Company: Updated company object

    Raises:
    - NotFound: Company does not exist
    - InvalidArgument: Invalid field values or update mask
    - PermissionDenied: Insufficient permissions to update company
    """

Usage Example:

from google.protobuf import field_mask_pb2

# Update company website and careers page
company.website_uri = "https://www.newacme.com"
company.career_site_uri = "https://jobs.newacme.com"

update_mask = field_mask_pb2.FieldMask(
    paths=["website_uri", "career_site_uri"]
)

updated_company = client.update_company(
    company=company, 
    update_mask=update_mask
)

Company Deletion

Removes company entities from the system. Note that companies with associated jobs cannot be deleted until all jobs are removed first.

def delete_company(self, name: str) -> None:
    """
    Deletes a company entity.

    Parameters:
    - name (str): Full company resource name

    Raises:
    - NotFound: Company does not exist
    - PermissionDenied: Insufficient permissions to delete company
    - FailedPrecondition: Company has associated jobs that must be deleted first
    """

Usage Example:

try:
    client.delete_company(
        name="projects/my-project/tenants/my-tenant/companies/company-123"
    )
    print("Company deleted successfully")
except exceptions.FailedPrecondition:
    print("Cannot delete company with active jobs")

Company Listing

Lists company entities with pagination support for efficient browsing of large company datasets within a tenant.

def list_companies(self, parent: str, page_size: int = None, 
                  page_token: str = None) -> ListCompaniesResponse:
    """
    Lists companies with pagination.

    Parameters:
    - parent (str): Tenant resource name
    - page_size (int): Maximum number of companies to return (max 100)
    - page_token (str): Token for pagination from previous response

    Returns:
    ListCompaniesResponse: Companies list with pagination token and metadata

    Raises:
    - InvalidArgument: Invalid page size
    - PermissionDenied: Insufficient permissions to list companies
    """

Usage Example:

# List all companies in a tenant
response = client.list_companies(
    parent="projects/my-project/tenants/my-tenant",
    page_size=50
)

for company in response.companies:
    print(f"Company: {company.display_name} ({company.external_id})")
    print(f"  Size: {company.size}")
    print(f"  Website: {company.website_uri}")

# Handle pagination
while response.next_page_token:
    response = client.list_companies(
        parent="projects/my-project/tenants/my-tenant",
        page_token=response.next_page_token,
        page_size=50
    )
    
    for company in response.companies:
        print(f"Company: {company.display_name}")

Company Data Model

Company Entity

class Company:
    name: str = None  # Resource name (auto-generated)
    display_name: str = None  # Company name (required, max 255 chars)
    external_id: str = None  # Client-defined company identifier (required, max 255 chars)
    size: CompanySize = None  # Company size category
    headquarters_address: str = None  # Main office address (max 1000 chars)
    hiring_organization: bool = None  # Whether company is actively hiring
    eeo_text: str = None  # Equal employment opportunity statement (max 1000 chars)
    website_uri: str = None  # Company website URL (max 2000 chars)
    career_site_uri: str = None  # Careers page URL (max 2000 chars)
    image_uri: str = None  # Company logo URL (max 2000 chars)
    keyword_searchable_job_custom_attributes: List[str] = None  # Searchable custom attributes
    derived_info: DerivedInfo = None  # Auto-derived company information
    suspended: bool = None  # Whether company is suspended

Company Size Classification

class CompanySize(Enum):
    """Company size categories based on employee count."""
    COMPANY_SIZE_UNSPECIFIED = 0
    MINI = 1  # Fewer than 50 employees
    SMALL = 2  # 50-99 employees
    SMEDIUM = 3  # 100-499 employees  
    MEDIUM = 4  # 500-999 employees
    BIG = 5  # 1,000-4,999 employees
    BIGGER = 6  # 5,000-9,999 employees
    GIANT = 7  # 10,000 or more employees

Derived Information

class Company.DerivedInfo:
    """Auto-derived company information populated by the system."""
    headquarters_location: Location = None  # Parsed headquarters location

Request and Response Types

Company Service Requests

class CreateCompanyRequest:
    parent: str = None  # Tenant resource name
    company: Company = None  # Company to create

class GetCompanyRequest:
    name: str = None  # Company resource name

class UpdateCompanyRequest:
    company: Company = None  # Company with updates
    update_mask: FieldMask = None  # Fields to update

class DeleteCompanyRequest:
    name: str = None  # Company resource name

class ListCompaniesRequest:
    parent: str = None  # Tenant resource name
    page_size: int = None  # Page size (max 100)
    page_token: str = None  # Pagination token

Company Service Responses

class ListCompaniesResponse:
    companies: List[Company] = None  # List of companies
    next_page_token: str = None  # Pagination token for next page
    metadata: ResponseMetadata = None  # Response metadata

Integration with Job Management

Companies serve as the parent entities for job postings and must be created before jobs can be posted:

# Create company first
company = client.create_company(parent=tenant_name, company=company_data)

# Then create jobs under that company
from google.cloud.talent import JobServiceClient, Job

job_client = JobServiceClient()
job = Job(
    company=company.name,  # Reference to created company
    requisition_id="job-001",
    title="Software Engineer",
    description="Join our team!"
)

job_client.create_job(parent=tenant_name, job=job)

Resource Path Helpers

The client provides helper methods for constructing resource paths:

# Class methods for building resource paths
@classmethod
def company_path(cls, project: str, tenant: str, company: str) -> str:
    """Constructs a fully-qualified company resource name."""

@classmethod  
def tenant_path(cls, project: str, tenant: str) -> str:
    """Constructs a fully-qualified tenant resource name."""

@classmethod
def parse_company_path(cls, path: str) -> Dict[str, str]:
    """Parses a company path into its component parts."""

Usage Example:

# Build resource paths
company_path = CompanyServiceClient.company_path(
    project="my-project",
    tenant="my-tenant", 
    company="company-123"
)

# Parse resource paths
path_components = CompanyServiceClient.parse_company_path(company_path)
print(f"Project: {path_components['project']}")
print(f"Tenant: {path_components['tenant']}")
print(f"Company: {path_components['company']}")

Error Handling

Company management operations can raise several types of exceptions:

from google.api_core import exceptions

try:
    company = client.create_company(parent=parent, company=company_data)
except exceptions.InvalidArgument as e:
    # Handle validation errors
    print(f"Invalid company data: {e}")
except exceptions.AlreadyExists as e:
    # Handle duplicate external_id
    print(f"Company already exists: {e}")
except exceptions.PermissionDenied as e:
    # Handle authorization errors
    print(f"Access denied: {e}")

Common error scenarios:

InvalidArgument: Missing required fields (display_name, external_id), invalid field values, malformed URIs
AlreadyExists: Duplicate external_id within the same tenant
NotFound: Company or tenant does not exist
PermissionDenied: Insufficient IAM permissions for company operations
FailedPrecondition: Cannot delete company with associated jobs
ResourceExhausted: API quota limits exceeded

Best Practices

External IDs: Use consistent, meaningful external_id values that map to your internal company identifiers
Company Profiles: Populate company profiles completely for better job search results and candidate experience
Logo Images: Use high-quality company logos with proper dimensions for best display
EEO Statements: Include appropriate equal opportunity employment statements for legal compliance
Website URLs: Ensure website and career site URLs are valid and regularly maintained
Company Hierarchy: For large organizations, consider how to model subsidiaries and divisions using external_id naming conventions

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-talent

docs

company-management.md

event-tracking.md

index.md

job-management.md

query-autocompletion.md

search-filtering.md

tenant-management.md

tile.json

tessl/pypi-google-cloud-talent