Documenation for hyperdiary

hyperdiary

A command line tool for writing diaries with hyperlinks. Free software, licensed under MIT license.

Installation

hyperdiary requires Python version 3.5 or later. Once you have Python and pip installed on your machine (and available in your path) you can install hyperdiary by executing

pip install hyperdiary

Setup

A project file hyperdiary.json is required to setup your diary. It should be of this form:

{
        "sources": [
                "2019/05.yaml",
                "2019/06.yaml"
        ],
        "expected": [
                {"start": "2019-05-01", "end": "2019-05-01"},
                {"start": "2019-06-09", "end": "2019-06-10"}
        ],
        "localization": {
                "months": ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
                           "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
                "date_fmt": "%-d.%-m.%Y"
        }
}

You diary content itself is entered in yaml files like this (2019/06.yaml):

2019-06-09:
  - Some entry goes here with a $special_identity|link
  - This entry is +surprise tagged +mytag +nexttag
  - This entry contains nothing new
2019-06-10:
  - Same $special_identity|link again and $New_Identity|NewIdentity
  - $test +mytag

Use $target|linktext to create a hyperlink to target showing text linktext. Use +mytag to add tag mytag.

Usage

usage: hyperdiary [-h]
          {check,stats,html,htmlfolder,hugo,tiddlers,tiddlywiki,view}
          ...

The hyperdiary main command line interface.

optional arguments:
        -h, --help            show this help message and exit

subcommands:
        {check,stats,html,htmlfolder,hugo,tiddlers,tiddlywiki,view}
                                Available subcommands
        check               Check entire diary for integrity up-to-dateness
        stats               Calculate impressive diary statistics
        html                Export diary to html
        htmlfolder          Export diary to html in folders
        hugo                Export diary to hugo static site format
        tiddlers            Export diary to tiddlywiki tiddlers format
        tiddlywiki          Export diary to tiddlywiki
        view                View entries on command line

Installation

Stable release

To install hyperdiary, run this command in your terminal:

$ pip install hyperdiary

This is the preferred method to install hyperdiary, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for hyperdiary can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/luphord/hyperdiary

Or download the tarball:

$ curl  -OL https://github.com/luphord/hyperdiary/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

hyperdiary

hyperdiary package

Submodules

hyperdiary.check module

hyperdiary.check.check(diary: hyperdiary.diary.Diary) → None

hyperdiary.diary module

exception hyperdiary.diary.BadEntryException

Bases: Exception

class hyperdiary.diary.DateRange(start: datetime.date, end: datetime.date)

Bases: object

static from_json(obj: Mapping[str, str]) → hyperdiary.diary.DateRange

class hyperdiary.diary.DayEntry(dt: datetime.date, lines: List[str])

Bases: object

Diary entry for a specific date, contains multiple lines of text.

iter_lines() → Iterable[Tuple[datetime.date, str]]

class hyperdiary.diary.Diary(hyperdiary_json: Mapping[KT, VT_co])

Bases: object

static discover(subpath: Union[pathlib.Path, str]) → hyperdiary.diary.Diary

static discover_and_load(path: Union[pathlib.Path, str] = '.') → hyperdiary.diary.Diary

iter_entries_by_year_and_month() → Iterable[Tuple[int, Iterable[Tuple[int, Iterable[hyperdiary.diary.DayEntry]]]]]

iter_lines() → Iterable[Tuple[datetime.date, str]]

load_entries() → None

nested_dicts_by_year_and_month() → Mapping[int, Mapping[int, Mapping[datetime.date, hyperdiary.diary.DayEntry]]]

class hyperdiary.diary.Token(type: hyperdiary.diary.TokenType, text: str, ref: str = None)

Bases: object

class hyperdiary.diary.TokenType

Bases: enum.Enum

An enumeration.

Id = 3

Tag = 2

Text = 1

hyperdiary.diary.find_ids(line: str) → Iterable[hyperdiary.diary.Token]

hyperdiary.diary.find_tags(line: str) → Iterable[hyperdiary.diary.Token]

>>> line = "+tag1 +tag2 some content goes here +tag3"
>>> res = [t.text for t in find_tags(line)]
>>> res == ["tag1", "tag2", "tag3"]
True

hyperdiary.diary.find_token_of_type(line: str, token_type: hyperdiary.diary.TokenType) → Iterable[hyperdiary.diary.Token]

hyperdiary.diary.tokenize(line: str) → Iterable[hyperdiary.diary.Token]

hyperdiary.html module

hyperdiary.html.append_li_a(ul: hyperdiary.htmltags.HTMLElement, text: str, href: str) → None

hyperdiary.html.day_to_html(current: datetime.date, entry: Iterable[str], localization: hyperdiary.localization.Localization, link_to_id_fn: Callable[[Optional[str]], str] = None) → hyperdiary.htmltags.HTMLElement

hyperdiary.html.diary_to_html(diary_instance: hyperdiary.diary.Diary, fname: str) → None

hyperdiary.html.diary_to_html_folder(diary_instance: hyperdiary.diary.Diary, folder: str) → None

hyperdiary.html.path_for_date(dt: datetime.date) → hyperdiary.simplepath.AbsolutePath

hyperdiary.html.rel_path(spath: Union[datetime.date, str, int]) → hyperdiary.simplepath.RelativePath

hyperdiary.html.wrap_html_page(content: Union[HTMLElement, str], title: str = None, level: int = 0) → hyperdiary.htmltags.html

hyperdiary.html.wrap_page(body_content: Union[HTMLElement, str], page_title: str = None, encoding: str = 'utf-8', css_references: Iterable[str] = [], inline_css: str = None) → hyperdiary.htmltags.html

hyperdiary.htmltags module

class hyperdiary.htmltags.HTMLElement(*content, **attributes)

Bases: object

append(*items) → hyperdiary.htmltags.HTMLElement

lazy_render(indent: str = '', add_indent: str = '') → Iterable[str]

lazy_render_attributes() → Iterable[str]

render_compact = False

subelement(item: hyperdiary.htmltags.HTMLElement) → hyperdiary.htmltags.HTMLElement

tag = 'div'

write(fname: str) → None

class hyperdiary.htmltags.a(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'a'

class hyperdiary.htmltags.article(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'article'

class hyperdiary.htmltags.body(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'body'

class hyperdiary.htmltags.button(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'button'

class hyperdiary.htmltags.div(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'div'

class hyperdiary.htmltags.footer(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'footer'

class hyperdiary.htmltags.form(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'form'

class hyperdiary.htmltags.h1(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'h1'

class hyperdiary.htmltags.h2(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'h2'

class hyperdiary.htmltags.h3(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'h3'

class hyperdiary.htmltags.h4(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'h4'

class hyperdiary.htmltags.head(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'head'

class hyperdiary.htmltags.header(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'header'

class hyperdiary.htmltags.hr(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'hr'

class hyperdiary.htmltags.html(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'html'

class hyperdiary.htmltags.img(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'img'

class hyperdiary.htmltags.li(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'li'

class hyperdiary.htmltags.link(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'link'

class hyperdiary.htmltags.meta(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'meta'

class hyperdiary.htmltags.nav(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'nav'

class hyperdiary.htmltags.ol(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'ol'

class hyperdiary.htmltags.p(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'p'

class hyperdiary.htmltags.small(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'small'

class hyperdiary.htmltags.span(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'span'

class hyperdiary.htmltags.style(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'style'

class hyperdiary.htmltags.table(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'table'

class hyperdiary.htmltags.tbody(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'tbody'

class hyperdiary.htmltags.td(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'td'

class hyperdiary.htmltags.th(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'th'

class hyperdiary.htmltags.thead(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'thead'

class hyperdiary.htmltags.title(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = True

tag = 'title'

class hyperdiary.htmltags.tr(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'tr'

class hyperdiary.htmltags.ul(*content, **attributes)

Bases: hyperdiary.htmltags.HTMLElement

render_compact = False

tag = 'ul'

hyperdiary.hugo module

hyperdiary.hugo.diary_to_hugo(diary_instance: hyperdiary.diary.Diary, folder: Union[pathlib.Path, str]) → None

hyperdiary.hugo.nice_date(dt: datetime.date) → str

hyperdiary.localization module

class hyperdiary.localization.Localization(months: List[str] = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'], days_short: List[str] = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'], date_fmt: str = '%Y-%m-%d')

Bases: object

format_date(dt: datetime.date) → str

Format to localized string. >>> l = Localization() >>> l.format_date(date(2019, 11, 3)) ‘2019-11-03’ >>> l = Localization(date_fmt=’%d.%m.%Y’) >>> l.format_date(date(2019, 11, 3)) ‘03.11.2019’

get_day_short(i: int) → str

Get the localized name of day i (zero-based index starting Monday). >>> l = Localization() >>> l.get_day_short(0) ‘Mon’ >>> l.get_day_short(6) ‘Sun’ >>> l.get_day_short(7) Traceback (most recent call last): … AssertionError >>> Localization(days_short=[‘Just Mon’]) Traceback (most recent call last): … AssertionError >>> l2 = Localization(days_short=list(‘1234567’)) >>> l2.get_day_short(3) ‘4’ >>> l2.get_day_short(6) ‘7’

get_month(i: int) → str

Get the localized name of month i (zero-based index). >>> l = Localization() >>> l.get_month(0) ‘January’ >>> l.get_month(11) ‘December’ >>> l.get_month(12) Traceback (most recent call last): … AssertionError >>> Localization(months=[‘Just January’]) Traceback (most recent call last): … AssertionError >>> l2 = Localization(months=list(‘123456789ond’)) >>> l2.get_month(3) ‘4’ >>> l2.get_month(10) ‘n’

hyperdiary.simplepath module

class hyperdiary.simplepath.AbsolutePath(path: str)

Bases: object

exception hyperdiary.simplepath.InvalidPathError

Bases: Exception

exception hyperdiary.simplepath.NotARelativePathError

Bases: hyperdiary.simplepath.InvalidPathError

exception hyperdiary.simplepath.NotAnAbsolutePathError

Bases: hyperdiary.simplepath.InvalidPathError

class hyperdiary.simplepath.RelativePath(path: str)

Bases: object

hyperdiary.stats module

hyperdiary.stats.stats(diary: hyperdiary.diary.Diary) → Dict[str, int]

hyperdiary.tiddlywiki module

class hyperdiary.tiddlywiki.Tiddler(fname: Union[pathlib.Path, str], **fields)

Bases: object

static from_entry(dt: datetime.date, entry: Iterable[str], localization: hyperdiary.localization.Localization) → hyperdiary.tiddlywiki.Tiddler

text

title

to_div() → str

to_tid() → str

hyperdiary.tiddlywiki.diary_to_tiddlers(diary_instance: hyperdiary.diary.Diary) → Iterator[hyperdiary.tiddlywiki.Tiddler]

hyperdiary.tiddlywiki.diary_to_tiddlers_export(diary_instance: hyperdiary.diary.Diary, tiddler_dir: Union[pathlib.Path, str]) → None

hyperdiary.tiddlywiki.diary_to_tiddlywiki_export(diary_instance: hyperdiary.diary.Diary, file: Union[pathlib.Path, str], tiddlywiki_base_file: Union[pathlib.Path, str]) → None

hyperdiary.tiddlywiki.make_tiddler_filename(o: Union[str, datetime.date]) → str

>>> make_tiddler_filename(" Frühstück Ähre Grüße Föhn")
'fruehstueck-aehre-gruesse-foehn.tid'
>>> make_tiddler_filename("a.v-_'üöß' tiddler")
'av-_ueoess-tiddler.tid'
>>> make_tiddler_filename(date(2019, 2, 3))
'2019-02-03.tid'

hyperdiary.view module

hyperdiary.view.view(diary: hyperdiary.diary.Diary, dt: datetime.date) → None

Module contents

hyperdiary.main() → None

hyperdiary.parse_date(sdate: str) → datetime.date

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/luphord/hyperdiary/issues.

If you are reporting a bug, please include:

• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

hyperdiary could always use more documentation, whether as part of the official hyperdiary docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/luphord/hyperdiary/issues.

If you are proposing a feature:

• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up hyperdiary for local development.

1. Fork the hyperdiary repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/hyperdiary.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv hyperdiary
   $ cd hyperdiary/
   $ python setup.py develop
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 hyperdiary tests
   $ python setup.py test or py.test
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 3.5, 3.6 and 3.7. Check https://travis-ci.com/github/luphord/hyperdiary/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ python -m unittest tests.test_hyperdiary

Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

Credits

Development Lead

• luphord <luphord@protonmail.com>

Contributors

None yet. Why not be the first?

History

0.6.1 (2020-10-21)

• add support for Python 3.8
• upgrade to flake8 3.8.4 and fix linter issues
• replace deprecated test command
• move to travis-ci.com

0.6.0 (2019-11-29)

• promote status to alpha
• introduced localization using hyperdiary.json; date format and month names so far
• added tiddlers for month (calendar) and year overview with hyperlinks
• Diary supports iteration by year/month
• make docs work

0.5.0 (2019-11-06)

• removed EntryType, refactored iteration, primarily passing Diary instances around
• fix bug when an ID is followed by a bracket )
• only line entries are allowed, no more dicts

0.4.0 (2019-10-30)

• full type annotations added for package
• linting and type checking in CI
• EntryTypes Dict and DictLine are deprecated and will be removed in 0.5 (check issues a warning)

0.3.2 (2019-10-17)

• fix linter configuration (and activate it)
• make all hyperdiary source files PEP8 conform
• set up bumpversion config

0.3.1 (2019-07-03)

• open date ranges iterate until yesterday, not today
• fix loading hyperdiary.json without expected field

0.3.0 (2019-06-19)

• Expected date ranges for check subcommand can be specified
• subcommand for export to tiddlywiki
• Tests for various output formats

0.2.0 (2019-06-12)

• stats subcommand can be invoked for all entries
• Rename tiddlywiki subcommand to tiddlers for different future usage
• Integrate Travis CI for automated testing
• Add basic tests
• Refactor diary/entry passing to subcommands

0.1.2 (2019-06-11)

• Fix htmlfolder subcommand by packaging picnic.min.css
• Fix view subcommand by using correct relative import
• Avoid deprecation warning in stats subcommand by using yaml.SafeLoader

0.1.1 (2019-04-29)

• Fix setup

0.1.0 (2019-04-28)

• First release on PyPI
• Import from fossil

Indices and tables

• Index
• Module Index
• Search Page