notesdir.repos package

Submodules

notesdir.repos.base module

Defines the API for accessing a user’s collection of notes.

The most important class is Repo.

class notesdir.repos.base.Repo

Bases: object

Base class for repos, which are responsible for reading, querying, and changing a user’s collection of notes.

Repo instances use notesdir.accessors.base.Accessor instances to read/write individual files, but add functionality that requires looking at more than one note in isolation (such as finding backlinks), and may also perform caching.

add_tag(path: str, tag: str) → None

Convenience method equivalent to calling change with one :class`notesdir.models.AddTagCmd`

change(edits: List[notesdir.models.FileEditCmd]) → None

Applies the specified edits and saves the affected files. Changes are applied in order.

May raise a notesdir.accessors.base.ChangeError or IO-related exception. Changes are generally not applied atomically.

If the repo performs caching, this method will ensure the changes are reflected in the cache, so it is not necessary to call invalidate() afterward.

close() → None

Release any resources associated with the repo. Should be called when you’re done with an instance.

del_tag(path: str, tag: str) → None

Convenience method equivalent to calling change with one :class`notesdir.models.DelTagCmd`

info(path: str, fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False)) → notesdir.models.FileInfo

Looks up the specified fields for the given file or folder.

Additional fields might or might not be populated.

May raise a notesdir.accessors.base.ParseError or IO-related exception, but otherwise will always return an instance. If no file or folder exists at the given path, or if the file type is unrecognized, it can still populate the path and backlinks attributes.

invalidate(only: Optional[Set[str]] = None) → None

If the repo uses a cache, this tells it to update the cache before the next read.

If only is non-empty, the repo might invalidate only those specific files, for the sake of performance.

It is not necessary to call this method when you have first created an instance, or after calling change(), as the repo should invalidate automatically at those times. But if you keep a repo instance around while also making direct changes to files yourself, you will need to call this method with the paths of the files you changed (or created or deleted).

This method might only look at filesystem metadata such as modification time, so there may be situations in which it fails to notice changes.

query(query: Union[str, notesdir.models.FileQuery] = FileQuery(include_tags=set(), exclude_tags=set(), sort_by=[]), fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False)) → Iterator[notesdir.models.FileInfo]

Returns the requested fields for all files matching the given query.

replace_href(path: str, original: str, replacement: str) → None

Convenience method equivalent to calling change with one notesdir.models.ReplaceRefCmd

set_created(path: str, created: datetime.datetime) → None

Convenience method equivalent to calling change with one notesdir.models.SetCreatedCmd

set_title(path: str, title: str) → None

Convenience method equivalent to calling change with one notesdir.models.SetTitleCmd

tag_counts(query: Union[str, notesdir.models.FileQuery] = FileQuery(include_tags=set(), exclude_tags=set(), sort_by=[])) → Dict[str, int]

Returns a map of tag names to the number of files matching the query which posses that tag.

notesdir.repos.direct module

Provides the DirectRepo class.

class notesdir.repos.direct.DirectRepo(conf: notesdir.conf.DirectRepoConf)

Bases: notesdir.repos.base.Repo

Accesses notes directly on the filesystem without any caching.

This performs fine if you only have a few dozen notes, but beyond that you want a caching implementation (see notesdir.repos.sqlite.SqliteRepo), because looking up backlinks for a file requires reading all the other files, which gets very slow.

conf: DirectRepoConf

change(edits: List[notesdir.models.FileEditCmd])

Applies the specified edits and saves the affected files. Changes are applied in order.

May raise a notesdir.accessors.base.ChangeError or IO-related exception. Changes are generally not applied atomically.

If the repo performs caching, this method will ensure the changes are reflected in the cache, so it is not necessary to call invalidate() afterward.

info(path: str, fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False), path_resolved=False, skip_parse=None) → notesdir.models.FileInfo

Looks up the specified fields for the given file or folder.

Additional fields might or might not be populated.

May raise a notesdir.accessors.base.ParseError or IO-related exception, but otherwise will always return an instance. If no file or folder exists at the given path, or if the file type is unrecognized, it can still populate the path and backlinks attributes.

invalidate(only: Optional[Set[str]] = None)

No-op.

query(query: Union[str, notesdir.models.FileQuery] = FileQuery(include_tags=set(), exclude_tags=set(), sort_by=[]), fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False)) → Iterator[notesdir.models.FileInfo]

Returns the requested fields for all files matching the given query.

tag_counts(query: Union[str, notesdir.models.FileQuery] = FileQuery(include_tags=set(), exclude_tags=set(), sort_by=[])) → Dict[str, int]

Returns a map of tag names to the number of files matching the query which posses that tag.

class notesdir.repos.direct.PathEntry(dir_entry, skip_parse)

Bases: tuple

dir_entry

Alias for field number 0

skip_parse

Alias for field number 1

notesdir.repos.sqlite module

Provides the SqliteRepo class.

class notesdir.repos.sqlite.SqliteRepo(conf: notesdir.conf.SqliteRepoConf)

Bases: notesdir.repos.direct.DirectRepo

Keeps a cache of note metadata/links in a SQLite database.

The database file is only a cache: you can safely delete it and it will be rebuilt the next time you create a SqliteRepo instance. Corrupting or deleting the file during operation may cause erratic behavior, though.

The modification timestamp and other filesystem metadata for each file in your note directories are stored in the database. Each time a SqliteRepo instance is created or change() is called, the files are scanned to see if this metadata has changed for any of them; if so, those files are parsed again and the cache is updated.

Remember to call close() when done with the instance, or use the instance as a context manager.

conf: notesdir.conf.SqliteRepoConf

change(edits: List[notesdir.models.FileEditCmd])

Applies the specified edits and saves the affected files. Changes are applied in order.

May raise a notesdir.accessors.base.ChangeError or IO-related exception. Changes are generally not applied atomically.

If the repo performs caching, this method will ensure the changes are reflected in the cache, so it is not necessary to call invalidate() afterward.

clear()

close()

Release any resources associated with the repo. Should be called when you’re done with an instance.

info(path: str, fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False), path_resolved=False) → notesdir.models.FileInfo

Looks up the specified fields for the given file or folder.

Additional fields might or might not be populated.

May raise a notesdir.accessors.base.ParseError or IO-related exception, but otherwise will always return an instance. If no file or folder exists at the given path, or if the file type is unrecognized, it can still populate the path and backlinks attributes.

invalidate(only: Optional[Set[str]] = None) → None

No-op.

query(query: Union[str, notesdir.models.FileQuery] = FileQuery(include_tags=set(), exclude_tags=set(), sort_by=[]), fields: Union[str, Iterable[str], notesdir.models.FileInfoReq] = FileInfoReq(path=True, links=True, tags=True, title=True, created=True, backlinks=False)) → Iterator[notesdir.models.FileInfo]

Returns the requested fields for all files matching the given query.

Module contents

Handles interaction with a collection of notes.

notesdir.repos.base.Repo defines an API. notesdir.repos.direct.DirectRepo is the most basic implementation, while notesdir.repos.sqlite.SqliteRepo is the caching implementation you usually want to use.