hired.search#

Job search functionality for the hired package.

This module provides a unified interface for searching jobs across multiple sources (Indeed, LinkedIn, USAJobs, Adzuna, etc.).

Example usage:

>>> from hired.search import JobSources, SearchCriteria
>>>
>>> # Create job sources facade
>>> sources = JobSources()
>>>
>>> # List available sources
>>> print(sources.list_available())
>>>
>>> # Search using a specific source
>>> criteria = SearchCriteria(
...     query="python developer",
...     location="San Francisco, CA",
...     results_wanted=20
... )
>>> results = sources.jobspy.search(criteria)
>>>
>>> # Or search across all sources
>>> all_results = sources.search_all(criteria)

Functions

`get_registry`()	Get the global source registry.
`register_source`(source[, source_class])	Register a source with the global registry.

Classes

`JobSources`([registry])	Main facade for accessing job search sources.
`SearchCriteria`(query[, location, country, ...])	Standardized search criteria across all sources.
`JobResult`(title, source[, company, ...])	Standardized job result across all sources.
`JobSearchSource`()	Abstract base class for job search sources.
`JobType`(*values)	Standardized job types across all sources.
`LocationInfo`([city, state, country, ...])	Location information for a job.
`CompensationInfo`([min_amount, max_amount, ...])	Compensation information for a job.
`SourceRegistry`()	Registry for job search sources.
`JobSpySource`([sites, proxies])	JobSpy source implementation.
`USAJobsSource`([api_key, email])	USAJobs API source implementation.
`AdzunaSource`([app_id, app_key, country])	Adzuna API source implementation.

Exceptions

SourceConfigError

Raised when a source is not properly configured.

class hired.search.AdzunaSource(app_id=None, app_key=None, country='us')[source]#

Bases: JobSearchSource

Adzuna API source implementation.

Searches international job postings via the Adzuna Jobs API. Requires a free API key from https://developer.adzuna.com/.

property display_name: str#: Return the display name of this source (e.g., ‘Indeed’, ‘USAJobs’).

get_setup_instructions()[source]#

Return setup instructions for this source.

Should include:

Where to get API keys if needed
Environment variables or config file settings
URLs for documentation

Return type:: str
Returns:: Multi-line string with setup instructions.

is_configured()[source]#

Check if this source is properly configured.

Return type:: bool
Returns:: True if the source is ready to use, False otherwise.

property name: str#: Return the name of this source (e.g., ‘indeed’, ‘usajobs’).

property requires_auth: bool#: Return True if this source requires authentication/API keys.

search(criteria)[source]#

Search for jobs using Adzuna API.

Parameters:: criteria (SearchCriteria) – Search criteria
Return type:: List[JobResult]
Returns:: List of JobResult objects

class hired.search.CompensationInfo(min_amount=None, max_amount=None, currency=None, interval=None)[source]#

Bases: object

Compensation information for a job.

class hired.search.JobResult(title, source, company=None, company_url=None, job_url=None, location=None, is_remote=None, description=None, job_type=None, compensation=None, date_posted=None, date_updated=None, application_deadline=None, skills=<factory>, benefits=<factory>, emails=<factory>, raw_data=<factory>)[source]#

Bases: object

Standardized job result across all sources.

This provides a unified interface regardless of which source the job was retrieved from.

to_dict()[source]#

Convert JobResult to dictionary.

Return type:: Dict[str, Any]

class hired.search.JobSearchSource[source]#

Bases: ABC

Abstract base class for job search sources.

All job search sources must implement this interface to be registered in the system.

abstract property display_name: str#: Return the display name of this source (e.g., ‘Indeed’, ‘USAJobs’).

abstractmethod get_setup_instructions()[source]#

Return setup instructions for this source.

Should include:

Where to get API keys if needed
Environment variables or config file settings
URLs for documentation

Return type:: str
Returns:: Multi-line string with setup instructions.

abstractmethod is_configured()[source]#

Check if this source is properly configured.

Return type:: bool
Returns:: True if the source is ready to use, False otherwise.

abstract property name: str#: Return the name of this source (e.g., ‘indeed’, ‘usajobs’).

abstract property requires_auth: bool#: Return True if this source requires authentication/API keys.

abstractmethod search(criteria)[source]#

Search for jobs using the given criteria.

Parameters:

criteria (SearchCriteria) – SearchCriteria object with search parameters

Return type:

List[JobResult]

Returns:

List of JobResult objects

Raises:

SourceConfigError – If the source is not properly configured
Exception – For other errors during search

validate_configured()[source]#

Validate that the source is configured, raise error if not.

Raises:: SourceConfigError – If the source is not properly configured
Return type:: None

class hired.search.JobSources(registry=None)[source]#

Bases: object

Main facade for accessing job search sources.

Provides both mapping interface (dict-like access) and attribute access to registered job sources.

Examples

>>> sources = JobSources()
>>> # List all available sources
>>> sources.list()
['jobspy', 'usajobs', 'adzuna']

>>> # Access via attribute
>>> results = sources.jobspy.search(SearchCriteria(query="python developer"))

>>> # Access via mapping
>>> results = sources['indeed'].search(SearchCriteria(query="data scientist"))

>>> # Search across multiple sources
>>> results = sources.search_all(
...     SearchCriteria(query="software engineer", location="San Francisco")
... )

get_info(name)[source]#

Get information about a source.

Parameters:: name (str) – Name of the source
Return type:: Dict[str, Any]
Returns:: Dictionary with source information including setup instructions

get_source(name)[source]#

Get a source by name.

Parameters:: name (str) – Name of the source
Return type:: JobSearchSource
Returns:: JobSearchSource instance
Raises:: KeyError – If source not found

keys()[source]#

Get list of source names (dict-like interface).

Return type:: List[str]

list()[source]#

List all registered sources.

Return type:: List[str]
Returns:: List of source names

list_available()[source]#

List sources that are configured and ready to use.

Return type:: List[str]
Returns:: List of configured source names

list_unconfigured()[source]#

List sources that need configuration.

Return type:: List[str]
Returns:: List of unconfigured source names

print_status()[source]#

Print the status of all registered sources.

Return type:: None

search(source_name, criteria)[source]#

Search using a specific source.

Parameters:

source_name (str) – Name of the source to use
criteria (SearchCriteria) – Search criteria

Return type:

List[JobResult]

Returns:

List of JobResult objects

search_all(criteria, sources=None, skip_unconfigured=True)[source]#

Search across multiple sources.

Parameters:

criteria (SearchCriteria) – Search criteria
sources (Optional[List[str]]) – Optional list of source names. If None, uses all available sources.
skip_unconfigured (bool) – If True, skip sources that are not configured

Return type:

List[JobResult]

Returns:

Combined list of JobResult objects from all sources

class hired.search.JobSpySource(sites=None, proxies=None)[source]#

Bases: JobSearchSource

JobSpy source implementation.

Uses python-jobspy to scrape jobs from multiple sources simultaneously. Does not require API keys, but may be subject to rate limiting.

property display_name: str#: Return the display name of this source (e.g., ‘Indeed’, ‘USAJobs’).

get_setup_instructions()[source]#

Return setup instructions for this source.

Should include:

Where to get API keys if needed
Environment variables or config file settings
URLs for documentation

Return type:: str
Returns:: Multi-line string with setup instructions.

is_configured()[source]#

Check if this source is properly configured.

Return type:: bool
Returns:: True if the source is ready to use, False otherwise.

property name: str#: Return the name of this source (e.g., ‘indeed’, ‘usajobs’).

property requires_auth: bool#: Return True if this source requires authentication/API keys.

search(criteria)[source]#

Search for jobs using JobSpy.

Parameters:: criteria (SearchCriteria) – Search criteria
Return type:: List[JobResult]
Returns:: List of JobResult objects

class hired.search.JobType(*values)[source]#

Bases: str, Enum

Standardized job types across all sources.

class hired.search.LocationInfo(city=None, state=None, country=None, postal_code=None, raw=None)[source]#

Bases: object

Location information for a job.

class hired.search.SearchCriteria(query, location=None, country=None, city=None, state=None, postal_code=None, distance_miles=None, job_type=None, is_remote=None, posted_within_days=None, results_wanted=20, offset=0, min_salary=None, max_salary=None, keywords=<factory>, exclude_keywords=<factory>, source_params=<factory>)[source]#

Bases: object

Standardized search criteria across all sources.

Different sources may not support all criteria, but this provides a consistent interface for users.

exception hired.search.SourceConfigError[source]#

Bases: Exception

Raised when a source is not properly configured.

class hired.search.SourceRegistry[source]#

Bases: object

Registry for job search sources.

Provides a plugin system where sources can be registered and retrieved by name.

get(name)[source]#

Get a source by name.

Parameters:: name (str) – Name of the source
Return type:: JobSearchSource
Returns:: JobSearchSource instance
Raises:: KeyError – If source not found

get_source_info(name)[source]#

Get information about a source.

Parameters:: name (str) – Name of the source
Return type:: Dict[str, Any]
Returns:: Dictionary with source information

list_available_sources()[source]#

List sources that are properly configured and ready to use.

Return type:: List[str]
Returns:: List of source names that are configured

list_sources()[source]#

List all registered source names.

Return type:: List[str]
Returns:: List of source names

list_unconfigured_sources()[source]#

List sources that are registered but not configured.

Return type:: List[str]
Returns:: List of source names that need configuration

register(source, source_class=None)[source]#

Parameters:

source (JobSearchSource) – Instance of a JobSearchSource implementation
source_class (Optional[Type[JobSearchSource]]) – Optional class of the source for reference

Return type:

None

unregister(name)[source]#

Unregister a source by name.

Parameters:: name (str) – Name of the source to unregister
Return type:: None

class hired.search.USAJobsSource(api_key=None, email=None)[source]#

Bases: JobSearchSource

USAJobs API source implementation.

Searches US Government job postings via the official USAJobs API. Requires a free API key from https://developer.usajobs.gov/.

property display_name: str#: Return the display name of this source (e.g., ‘Indeed’, ‘USAJobs’).

get_setup_instructions()[source]#

Return setup instructions for this source.

Should include:

Where to get API keys if needed
Environment variables or config file settings
URLs for documentation

Return type:: str
Returns:: Multi-line string with setup instructions.

is_configured()[source]#

Check if this source is properly configured.

Return type:: bool
Returns:: True if the source is ready to use, False otherwise.

property name: str#: Return the name of this source (e.g., ‘indeed’, ‘usajobs’).

property requires_auth: bool#: Return True if this source requires authentication/API keys.

search(criteria)[source]#

Search for jobs using USAJobs API.

Parameters:: criteria (SearchCriteria) – Search criteria
Return type:: List[JobResult]
Returns:: List of JobResult objects

hired.search.get_registry()[source]#

Get the global source registry.

Return type:: SourceRegistry

hired.search.register_source(source, source_class=None)[source]#

Parameters:

source (JobSearchSource) – Instance of a JobSearchSource implementation
source_class (Optional[Type[JobSearchSource]]) – Optional class of the source for reference

Return type:

None

Modules

`base`	Base classes and interfaces for job search functionality.
`facade`	Main facade for job search functionality.
`registry`	Registry system for managing job search sources.
`sources`	Job search source implementations.