This is a utility library for providing functions to generate and modify Org mode syntax elements like headings, links, time-stamps, or date-stamps.
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('Bob@example.com'),
'[[mailto:Bob@example.com][Bob@example.com]]')
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.
''')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
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_timeandinactive - 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
- more parameters for
- 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(): addedrepeater_or_delaygenerate_headining(): addedscheduled_timestampanddeadline_timestamp
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
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