Documentation
¶
Overview ¶
Package ncbi is the library behind the ncbi command line: the HTTP client, request shaping, and the typed data models for the NCBI Entrez eUtils API.
The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.
Index ¶
- Constants
- type Article
- type Client
- func (c *Client) FetchArticles(ctx context.Context, pmids []string) ([]*Article, error)
- func (c *Client) FetchGenes(ctx context.Context, ids []string) ([]*Gene, error)
- func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)
- func (c *Client) GetArticle(ctx context.Context, pmid string) (*Article, error)
- func (c *Client) Search(ctx context.Context, db, query string, limit int) (*SearchResult, error)
- func (c *Client) SearchGenes(ctx context.Context, query string, limit int) ([]*Gene, error)
- func (c *Client) SearchPubMed(ctx context.Context, query string, limit int) ([]*Article, error)
- type Config
- type Domain
- type Gene
- type SearchResult
Constants ¶
const DefaultUserAgent = "ncbi-cli/dev (+https://github.com/tamnd/ncbi-cli)"
DefaultUserAgent identifies the client to NCBI. A real, honest User-Agent is both polite and the thing most likely to keep you unblocked.
const EUtilsBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
EUtilsBase is the root every eUtils request is built from.
const Host = "pubmed.ncbi.nlm.nih.gov"
Host is the PubMed site, used for Locate / URI resolution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Article ¶
type Article struct {
PMID string `json:"pmid" kit:"id"`
Title string `json:"title"`
Authors []string `json:"authors"`
Journal string `json:"journal"`
PubDate string `json:"pub_date"`
Volume string `json:"volume,omitempty"`
Pages string `json:"pages,omitempty"`
}
Article is a PubMed article record.
type Client ¶
Client talks to the NCBI eUtils API over HTTP.
func NewClientWithConfig ¶
NewClientWithConfig returns a Client using the given config.
func (*Client) FetchArticles ¶
FetchArticles fetches esummary for a batch of PMIDs and returns Article records.
func (*Client) FetchGenes ¶
FetchGenes fetches esummary for a batch of Gene IDs.
func (*Client) Get ¶
Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.
func (*Client) GetArticle ¶
GetArticle fetches a single PubMed article by PMID.
func (*Client) Search ¶
Search runs an esearch query against the named database and returns a SearchResult with the matching IDs (up to limit).
func (*Client) SearchGenes ¶
SearchGenes searches the Gene database and returns full Gene records.
type Config ¶
type Config struct {
BaseURL string
APIKey string
UserAgent string
Rate time.Duration
Timeout time.Duration
Retries int
}
Config carries the tunable parameters for the NCBI client.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults for the free-tier NCBI eUtils API (3 req/s without a key).
type Domain ¶
type Domain struct{}
Domain is the NCBI driver. It carries no state; the per-run client is built by the factory Register hands kit.
func (Domain) Classify ¶
Classify turns any accepted input into the canonical (type, id). A bare string of digits is a PMID; a full pubmed URL is also recognised.
func (Domain) Info ¶
func (Domain) Info() kit.DomainInfo
Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.
type Gene ¶
type Gene struct {
ID string `json:"id" kit:"id"`
Symbol string `json:"symbol"`
Name string `json:"name"`
Organism string `json:"organism"`
Chromosome string `json:"chromosome,omitempty"`
Summary string `json:"summary,omitempty"`
}
Gene is a record from the NCBI Gene database.
type SearchResult ¶
type SearchResult struct {
DB string `json:"db" kit:"id"`
Count int `json:"count"`
IDs []string `json:"ids"`
}
SearchResult is a generic search result: IDs and count from any NCBI DB.
Source Files