• orgformat

This is a utility library for providing functions to generate and modify [[https://orgmode.org][Org mode]] syntax elements like [[https://orgmode.org/manual/Headlines.html#Headlines][headings]], [[https://orgmode.org/manual/External-links.html][links]], [[https://orgmode.org/manual/Timestamps.html#Timestamps][time-stamps]], or date-stamps.

** Documentation

You can find the [[http://htmlpreview.github.io/?https://github.com/novoid/orgformat/blob/master/orgformat.html][pydoc documentation in HTML here]]. Sorry for the default colors of pydoc.

I also consider [[file:orgformat/orgformat_test.py][the unit tests as a good starting point]] to learn about the features provided.

Just a few examples:

#+BEGIN_SRC python 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. ''') #+END_SRC

** Installation

This tool needs [[http://www.python.org/downloads/][Python 3 to be installed]].

You can install orgformat stand-alone via [[https://packaging.python.org/tutorials/installing-packages/][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:
  • [[https://www.python.org/dev/peps/pep-0484/][Python type annotations]] added for [[https://mypy.readthedocs.io/en/latest/index.html][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 [[file:orgformat.html][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 [[https://github.com/novoid/Memacs][Memacs]].

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

• [[https://github.com/novoid/lazyblorg][lazyblorg]]
• [[https://github.com/novoid/appendorgheading][appendorgheading]] is basically a Python wrapper script for =generate_headining()= to be used from command line

• How to Thank Me

--- BEGIN SHARED: how_to_thank_me --- see https://github.com/novoid/screencasts/

I'm glad if you like my tool. I've got way more projects on:

• [[https://github.com/novoid/][GitHub]] (oldest projects),
• [[https://gitlab.com/publicvoit/][GitLab.com]] (older projects), and
• [[https://codeberg.org/publicvoit/][Codeberg]] (newest projects).

If you want to support me:

• [[https://karl-voit.at/2018/06/07/cardware/][Send old-fashioned postcard per snailmail]] - I love personal feedback!
  • see [[http://tinyurl.com/j6w8hyo][my address]]
• Send feature wishes or improvements as an issue
• Create issues for bugs
• Contribute merge requests for bug fixes
• Check out my other cool projects on the platforms above

If you want to contribute to this cool project, please fork and contribute!

I am using [[http://www.python.org/dev/peps/pep-0008/][Python PEP8]] and occasionally some ideas from [[http://en.wikipedia.org/wiki/Test-driven_development][Test Driven Development (TDD)]]. I fancy Python3 with [[https://typing.python.org/en/latest/spec/annotations.html][type annotations]], although I'm not using them everywhere at the moment. Starting with 2025, I began to use help from Claude.ai which is a huge improvement, given my lack of programming practice and knowledge.

After all, each of my tools was developed because I needed its functionality and could not get it elsewhere - at least to my knowledge or taste.

--- END SHARED: how_to_thank_me --- see https://github.com/novoid/screencasts/

• Local Variables :noexport:

Local Variables:

mode: auto-fill

mode: flyspell

eval: (ispell-change-dictionary "en_US")

End: