novoid / orgformat

Utility library for providing functions to generate and modify Org mode syntax elements like links, time-stamps, or date-stamps.

orgformat

This is a utility library for providing functions to generate and modify Org mode syntax elements like headings, links, time-stamps, or date-stamps.

Documentation

You can find the pydoc documentation in HTML here. Sorry for the default colors of pydoc.

I also consider the unit tests as a good starting point to learn about the features provided.

Just a few examples:

        self.assertEqual(OrgFormat.orgmode_timestamp_to_datetime(
            '<1980-12-31 Wed 23:59>'),
                         datetime.datetime(1980, 12, 31, 23, 59, 0, tzinfo=None))

        self.assertEqual(OrgFormat.apply_timedelta_to_org_timestamp(
            '<2019-11-06 Wed 00:59>', -2.0), '<2019-11-05 Tue 22:59>')

        self.assertEqual(OrgFormat.date(time.strptime('2011-11-02T20:38', '%Y-%m-%dT%H:%M'), 
                                        inactive=False,
                                        repeater_or_delay='+2w '),
                         '<2011-11-02 Wed +2w>')

        self.assertEqual(
            OrgFormat.daterange_autodetect_time(
                time.strptime('2011-11-29', '%Y-%m-%d'),
                time.strptime('2011-11-30T23:59', '%Y-%m-%dT%H:%M'), inactive=True),
            '[2011-11-29 Tue 00:00]--[2011-11-30 Wed 23:59]')

        self.assertEqual(OrgFormat.strdate('2011-11-03T23:59'), '<2011-11-03 Thu>')
        self.assertEqual(OrgFormat.strdate('2011-11-30 21:06', show_time=True, repeater_or_delay=' +7y   '),
                         '<2011-11-30 Wed 21:06 +7y>')

        self.assertEqual(OrgFormat.parse_extended_iso_datetime("2011-1-2T3:4:5"),
                         time.strptime('2011-01-02 03.04.05', '%Y-%m-%d %H.%M.%S'))


        self.assertEqual(
            OrgFormat.date(
                OrgFormat.parse_basic_iso_datetime('20111219T205510Z'), True
            ),
            '<2011-12-19 Mon 21:55>'
        )

        self.assertEqual(OrgFormat.mailto_link('[email protected]'),
                         '[[mailto:[email protected]][[email protected]]]')

        self.assertEqual(OrgFormat.dhms_from_sec(99999), '1d 3:46:39')

        self.assertEqual(OrgFormat.generate_heading(level=1,
                                                    keyword='TODO',
                                                    priority='A',
                                                    title='This is my title',
                                                    tags=['foo', 'bar_baz'],
                                                    scheduled_timestamp='<2019-12-29 Sun 11:35>',
                                                    deadline_timestamp='<2019-12-30 Mon 23:59>',
                                                    properties=[('CREATED', OrgFormat.strdate('2011-11-03 23:59', inactive=True, show_time=True)),
                                                                ('myproperty','foo bar baz')],
                                                    section=' With this being\nthe content of the heading section.'),
'''* TODO [#A] This is my title  :foo:bar_baz:
SCHEDULED: <2019-12-29 Sun 11:35> DEADLINE: <2019-12-30 Mon 23:59>
:PROPERTIES:
:CREATED: [2011-11-03 Thu 23:59]
:myproperty: foo bar baz
:END:

 With this being
the content of the heading section.
''')

Installation

This tool needs Python 3 to be installed.

You can install orgformat stand-alone via pip:

pip3 install orgformat

If you are using a project that is referring to orgformat, this library usually gets added to the requirements.txt file of that project and installed when you do invoke:

pip3 install -r requirements.txt

Changelog

This changelog does not list all commits/changes, just the substantial ones.

• 2019.11.03.1: Finished moving from Memacs and lazyblorg to a separate library
• 2019.11.06.1:
  • Python type annotations added for mypy checks
  • Refactoring, simplification, unification:
    • more parameters for show_time and inactive
    • removed some very basic and so-far unused wrappers for other functions
    • removed functions for detailed parameters that got replaced by more generalized functions
    • renamed some functions
  • Unit tests for all functions ;-)
  • Much better documentation including examples
  • Don’t worry about these breaking changes: Memacs and lazyblorg (the only projects using this library so far) were adapted accordingly and therefore nobody else is affected. No breaking changes like this in the future.
• 2019.12.28.1: generate_heading()
• 2019.12.29.1:
  • date(), strdate(): added repeater_or_delay
  • generate_headining(): added scheduled_timestamp and deadline_timestamp

History

This file was initially written mainly by https://github.com/awieser and was part of Memacs.

As of 2019-10-31, this file is moved to an independent library since multiple projects are using its functions such as:

• lazyblorg
• appendorgheading is basically a Python wrapper script for generate_headining() to be used from command line

How to Thank Me

I’m glad you like my tools. If you want to support me:

• Send old-fashioned postcard per snailmail - I love personal feedback!
  • see my address
• Send feature wishes or improvements as an issue on GitHub
• Create issues on GitHub for bugs
• Contribute merge requests for bug fixes
• Contribute unit tests
• Check out my other cool projects on GitHub

Local Variables

orgformat's Issues

Unit tests at least for basic functionality of all functions

So far, unit tests were not done for everything. This should provide at least unit tests that show the basic good-cases of each function.

Support localized weekdays in Org-mode time-stamps

Currently, only English and German day abbreviations are supported for parsing and I think only English for generating Org-mode time- and date-stamps.

A good start would be to accept all 2- and 3-letter characters as day strings, ignoring them for any further processing. For generating, English might be the best choice since everything else would require much more effort.

Reported via https://mastodon.technology/@temporal/107292008689723153

README should list and explain at least most important functions

New people have to read the source code in order to understand what this library stands for. Please do extend the README with at least some examples to motivate installing and using this library.

Just a typo...

In the Readme, it says:

"You can install filetags via pip:"

Should be "orgformat" I think.