naturtag.settings module#

Basic utilities for reading and writing settings from config files

class naturtag.settings.Settings(path=None, dark_mode=False, window_size=(1500, 1024), log_level='INFO', log_level_external='INFO', show_logs=False, all_ranks=False, casual_observations=True, locale='en', preferred_place_id=1, search_locale=True, username='', common_names=True, hierarchical=True, sidecar=True, exif=True, iptc=True, xmp=True, default_image_dir=PosixPath('/home/docs'), use_last_dir=True, recent_image_dirs=_Nothing.NOTHING, favorite_image_dirs=_Nothing.NOTHING, debug=False, setup_complete=False, last_obs_check=None)#

Bases: YamlMixin

add_favorite_dir(image_dir)#

add_recent_dir(path)#: Add a directory to the list of recent image directories

all_ranks: bool#

casual_observations: bool#

common_names: bool#

dark_mode: bool#

property data_dir: Path#

property db_path: Path#

debug: bool#

default_image_dir: Path#

exif: bool#

favorite_image_dirs: list[Path]#

hierarchical: bool#

property image_cache_path: Path#

iptc: bool#

last_obs_check: Optional[datetime]#

locale: str#

log_level: str#

log_level_external: str#

property logfile: Path#

preferred_place_id: int#

classmethod read(path=PosixPath('/home/docs/.local/share/Naturtag/settings.yml'))#

Read settings from config file

Return type:: Settings

recent_image_dirs: list[Path]#

remove_favorite_dir(image_dir)#

remove_recent_dir(image_dir)#

search_locale: bool#

set_obs_checkpoint()#

setup_complete: bool#

show_logs: bool#

sidecar: bool#

property start_image_dir: Path#: Get the starting directory for image selection, depending on settings

use_last_dir: bool#

property user_taxa_path: Path#

username: str#

window_size: tuple[int, int]#

xmp: bool#

class naturtag.settings.UserTaxa(path=None, history=_Nothing.NOTHING, starred=_Nothing.NOTHING, observed=_Nothing.NOTHING)#

Bases: YamlMixin

Relevant taxon IDs stored for the current user

property display_ids: set[int]#: Return top history, frequent, observed, and starred taxa combined. Returns only unique IDs, since a given taxon may appear in more than one list.

frequent: Counter[int] = None#

frequent_idx(taxon_id)#

Return the position of a taxon in the frequent list, if it’s in the top MAX_DISPLAY_HISTORY taxa.

Return type:: Optional[int]

history: list[int]#

observed: dict[int, int]#

path: Optional[Path]#

classmethod read(path)#

Read settings from config file

Return type:: UserTaxa

starred: list[int]#

property top_frequent: list[int]#: Get the most frequently viewed taxa

property top_history: list[int]#: Get the most recently viewed unique taxa

property top_observed: list[int]#: Get the most commonly observed taxa

update_history(taxon_id)#: Update history and frequent with a new or existing taxon ID

update_observed(taxon_counts)#

view_count(taxon_id)#

Return the number of times this taxon has been viewed

Return type:: int

class naturtag.settings.YamlMixin(path=None)#

Bases: object

Attrs class mixin that converts to and from a YAML file

path: Optional[Path]#

classmethod read(path)#

Read settings from config file

Return type:: YamlMixin

reset_defaults()#

write()#: Write settings to config file

naturtag.settings.doc_field(doc='', **kwargs)#: Create a field for an attrs class that is documented in the class docstring.

naturtag.settings.make_converter()#

Return type:: Converter

naturtag.settings.setup(settings=None, overwrite=False, download=False)#

Run any first-time setup steps, if needed: * Create database tables * Extract packaged taxonomy data and load into SQLite

Note: taxonomy data is included with PyInstaller packages and platform-specific installers, but not with plain python package on PyPI (to keep package size small). Use download=True to fetch the missing data.

Parameters:

settings (Optional[Settings]) – Existing settings object
overwrite (bool) – Overwrite an existing taxon database, if it already exists
download (bool) – Download taxon data (full text search + basic taxon details)