Skip to content

Commit

Permalink
Split user guide into basic and advanced usage
Browse files Browse the repository at this point in the history
  • Loading branch information
@JWCook
JWCook committed Dec 11, 2023
1 parent 142ec28 commit d77ad46
Show file tree
Hide file tree
Showing 5 changed files with 191 additions and 180 deletions.
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@
# Enable automatic links to other projects' Sphinx docs
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'requests': ('https://requests.readthedocs.io/en/master/', None),
'requests': ('https://requests.readthedocs.io/en/latest/', None),
'requests_cache': ('https://requests-cache.readthedocs.io/en/stable/', None),
'requests_ratelimiter': ('https://requests-ratelimiter.readthedocs.io/en/latest/', None),
'urllib3': ('https://urllib3.readthedocs.io/en/stable/', None),
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
```{toctree}
:maxdepth: 2
user_guide
user_guide/index
examples
endpoints
reference
Expand Down
185 changes: 7 additions & 178 deletions docs/user_guide.md → docs/user_guide/advanced.md
View file
Original file line number Diff line number Diff line change
@@ -1,172 +1,5 @@
(user_guide)=
# {fa}`book` User Guide
This page summarizes how to use the main features of pyinaturalist.

## Installation
Installation instructions:

::::{tab-set}
:::{tab-item} Pip
Install the latest stable version with pip:
```
pip install pyinaturalist
```
:::
:::{tab-item} Conda
Or install from conda-forge, if you prefer:
```
conda install -c conda-forge pyinaturalist
```
:::
:::{tab-item} Pre-release
If you would like to use the latest development (pre-release) version:
```
pip install --pre pyinaturalist
```
:::
:::{tab-item} Local development
See {ref}`contributing` for details on setup for local development.
:::
::::

:::{admonition} Python version compatibility
:class: toggle, tip

pyinaturalist currently requires **python 3.7+**. If you need to use an older version
of python, here are the last compatible versions of pyinaturalist:

* **python 2.7:** pyinaturalist 0.1
* **python 3.4:** pyinaturalist 0.10
* **python 3.5:** pyinaturalist 0.11
* **python 3.6:** pyinaturalist 0.16
* **python 3.7:** still supported, but expected to be dropped in a future release
:::

## Imports
You can import all public functions and classes from the top-level `pyinaturalist` package:
```
>>> from pyinaturalist import Taxon, get_observations, pprint # etc.
```

Or you can just import everything:
```
>>> from pyinaturalist import *
```

## Requests
Requests generally follow the same format as the [API](https://api.inaturalist.org/v1)
and [search URLs](https://forum.inaturalist.org/t/how-to-use-inaturalists-search-urls-wiki).

For example, if you wanted to search observations by user, these three requests are equivalent:

::::{tab-set}
:::{tab-item} search URL
```
https://www.inaturalist.org/observations?user_id=tiwane,jdmore
```
:::
:::{tab-item} API request
```
https://api.inaturalist.org/v1/observations?user_id=tiwane%2Cjdmore
```
:::
:::{tab-item} pyinaturalist search
```python
>>> get_observations(user_id=['tiwane', 'jdmore'])
```
:::
::::

Compared to search URLs and raw API requests, pyinaturalist provides some conveniences for making
requests easier:
* Python lists instead of comma-separated strings
* Python booleans instead of JS-style boolean strings or `1`/`0`
* Python file-like objects or file paths for photo and sound uploads
* Python {py:class}`~datetime.date` and {py:class}`~datetime.datetime` objects instead of date/time strings
* Simplified data formats for `POST` and `PUT` requests
* Simplified pagination
* Validation for multiple-choice parameters

And more, depending on the function.
See the {ref}`reference-docs` section for a complete list of functions available.

## Responses
API responses are returned as JSON, with some python type conversions applied (similar to the
request type conversions mentioned above). Example response data is shown in the documentation for
each request function, for example {py:func}`~pyinaturalist.v1.observations.get_observations`.

### API Data vs Web UI
Here is how some of those response fields correspond to observation details shown on
iNaturalist.org:
```{figure} images/inat-observation-page-annotated.png
```

And here is what that same observation looks like in JSON:
:::{admonition} Observation response JSON
:class: toggle
```{literalinclude} sample_data/get_observation_2.json
```
:::

### Previewing Responses
These responses can contain large amounts of response attributes, making it somewhat cumbersome if you
just want to quickly preview results (for example, in a Jupyter notebook). For that purpose, the
{py:func}`~pyinaturalist.formatters.pprint` function is available to format response data as a
condensed, color-highlighted table.

**Examples:**

::::{tab-set}
:::{tab-item} Observations
```
>>> from pyinaturalist import get_observations, pprint
>>> observations = get_observations(user_id='niconoe', per_page=5)
>>> pprint(observations)
ID Taxon ID Taxon Observed on User Location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
82974075 61546 Species: Nemophora degeerella (Yellow-barred Longhorn) Jun 14, 2021 niconoe 1428 Braine-l'Alleud, Belgique
82827577 48201 Family: Scarabaeidae (Scarabs) Jun 13, 2021 niconoe 1428 Braine-l'Alleud, Belgique
82826778 48201 Family: Scarabaeidae (Scarabs) Jun 13, 2021 niconoe 1428 Braine-l'Alleud, Belgique
82696354 209660 Species: Chrysolina americana (Rosemary Beetle) Jun 12, 2021 niconoe 1420 Braine-l'Alleud, Belgique
82696334 472617 Species: Tomocerus vulgaris Jun 07, 2021 niconoe 1428 Braine-l'Alleud, Belgique
```
:::
:::{tab-item} Places
```
>>> from pyinaturalist import get_places, pprint
>>> places = get_places_autocomplete('Vale')
>>> pprint(places)
ID Latitude Longitude Name Category URL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
96877 49.5189 -2.5190 Vale https://www.inaturalist.org/places/96877
21951 -16.8960 -40.8349 Fronteira dos Vales https://www.inaturalist.org/places/21951
23663 -6.3677 -41.8001 Valença do Piauí https://www.inaturalist.org/places/23663
24222 -27.2220 -53.6338 Pinheirinho do Vale https://www.inaturalist.org/places/24222
24374 -29.8309 -52.1121 Vale Verde https://www.inaturalist.org/places/24374
24442 -10.3841 -62.0939 Vale do Paraíso https://www.inaturalist.org/places/24442
103902 44.7355 27.5412 Valea Ciorii https://www.inaturalist.org/places/103902
103905 44.7529 26.8481 Valea Macrisului https://www.inaturalist.org/places/103905
105015 44.6805 24.0224 Valea Mare https://www.inaturalist.org/places/105015
104268 46.7917 27.0905 Valea Ursului https://www.inaturalist.org/places/104268
```
:::
:::{tab-item} Places (with terminal colors)
```{figure} images/pprint_table.png
```
:::
::::

## Models
Data models ({py:mod}`pyinaturalist.models`) are included for all API response types. These allow
working with typed python objects instead of raw JSON. These are not used by default in the API query
functions, but you can easily use them as follows:
```python
>>> from pyinaturalist import Observation, get_observations
>>> response = get_observations(user_id='my_username)
>>> observations = Observation.from_json_list(response)
```

In a future release, these models will be fully integrated with the API query functions.
# Advanced Usage
This page describes some advanced features of pyinaturalist.

## Pagination
Most endpoints support pagination, using the parameters:
Expand Down Expand Up @@ -204,7 +37,7 @@ iNaturalist uses OAuth2, which provides several different methods (or "flows") t
For example, on the [login page](https://www.inaturalist.org/login), you have the option of logging
in with a username/password, or with an external provider (Google, Facebook, etc.):

```{image} images/inat-user-login.png
```{image} ../images/inat-user-login.png
:alt: Login form
:width: 150
```
Expand All @@ -227,14 +60,14 @@ following pieces of information:
* **URL and Redirect URI:** Just enter the URL to your GitHub repo, if you have one; otherwise any
placeholder like "<https://www.inaturalist.org>" will work.

```{image} images/inat-new-application.png
```{image} ../images/inat-new-application.png
:alt: New Application form
:width: 300
```

You should then see a screen like this, which will show your new application ID and secret. These will
only be shown once, so save them somewhere secure, preferably in a password manager.
```{image} images/inat-new-application-complete.png
```{image} ../images/inat-new-application-complete.png
:alt: Completed application form
:width: 400
```
Expand Down Expand Up @@ -347,7 +180,7 @@ across multiple machines. [KeePassXC](https://keepassxc.org/) offers this featur
macOS and Linux systems. See this guide for setup info:
[KeepassXC and secret service, a small walk-through](https://avaldes.co/2020/01/28/secret-service-keepassxc.html).

```{figure} images/password_manager_keying.png
```{figure} ../images/password_manager_keying.png
Credentials storage with keyring + KeePassXC
```

Expand Down Expand Up @@ -533,8 +366,4 @@ session object used to make requests:
```python
>>> from pyinaturalist import ClientSession
>>> session = ClientSession(user_agent='my_app/1.0.0')
```

## API Recommended Practices
See [API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices)
on iNaturalist for more general usage information and notes.
```
Loading

0 comments on commit d77ad46

Please sign in to comment.