Skip to content

A simple python script to parse desired org file(s) entries by specified parameters and generate a file to sync with orgzly.

Notifications You must be signed in to change notification settings

anoduck/org-orgzly

Repository files navigation

Org-Orgzly

./Resources/README/org-orgzly_logo.png

  ___                ___              _
 / _ \ _ _ __ _ ___ / _ \ _ _ __ _ __| |_  _
| (_) | '_/ _` |___| (_) | '_/ _` |_ / | || |
 \___/|_| \__, |    \___/|_| \__, /__|_|\_, |
          |___/              |___/      |__/

Org-orgzly

A python application to parse and generate org files for orgzly practically, by making managing your org schedule easier.

New Breaking Changes - Dec 03 2022

Please see the heading below concerning integration of attachments and event files for details.

Issues/Bugs?

If you experience ANY issues using this script, encounter ANY bugs, or you just think this script sucks. PLEASE, submit and issue to either the github or codeberg repositories, and we will try our best to address the issue as soon as feasibly possible.

About

What it does

This script takes a specified list of org files, extracts org entries, filters out entries that do not meet specified TODO and Date parameters, provides allowances for days in a month and leap years, and then writes those entries to the designated orgzly inbox. It then uploads designated orgzly files to Dropbox. Then later on, the user may download those files from Dropbox, and merge entries from the orgzly inbox back to org via the org inbox file.

Features

  • Processes org nodes for only a particularly defined amount of days, and add them to your orgzly inbox.
  • Allows for retrieving created org nodes inside your orgzly inbox to your org inbox.
  • Compensates for leap years.
  • Uploads orgzly files to a defined folder in your dropbox account
  • Downloads orgzly files to a defined local folder on your local machine.
  • Lists contents of the remote orgzly folder within dropbox
  • Eleminates duplicate entries

Methodological Assumptions

There are several assumptions made concerning time management and the use of orgzly.

  • Evidently orgzly was never intended to be a replacement for emacs.
  • The user does not desire to sync all org agenda files with orgzly.
  • Mobile management of many org entries is difficult.
  • Duplicate org entries are not cool.
  • Only having a few entries covering the immediate future is all that is needed.

What is required

Admittedly, there are many limitations to the application, so don’t go all willy nilly on it. In order for the program to discover and use your nodes, you will need to use a todo keyword, and either a deadline or a scheduled date. Traversal of multileveled org entries should be capable, due to the script processing all entries that possess the previously required properties.

Installation

Since in order to make use of this library it is assumed one has reasonable apprehension of EMACS use, is familiar with using git, and knows how to execute a python script inside shell.

Preferred installation method

It would be to the user’s benefit to clone the source directly from the repository using git clone https://codeberg.org/anoduck/org-orgzly. As, this would provide the user with the most recent version of the script with all newly added features. Please consider the releases as existing for historical notation.

Required Python libraries

  • orgparse
  • configobj
  • validate
  • art
  • dropbox

The ‘ini’ file

The configuration file, config.ini will be automatically generated for you in your XDG_CONFIG_HOME directory under the org-orgzly folder, with the default values already filled out for you. If you plan on using this script in conjunction with the Dropbox service, then you will need to change the values of app_key and app_secret respectively with the values corresponding to the app your created in the dropbox Dropbox App Console. More information can be found out concerning the dropbox api below.

All configuration values are REQUIRED, and although they do provide the user to customize the script, there are some systematic implementations that must be accommodated in facilitation of your org-task management system. Most notably is the implementation of an inbox.org file to place new and unorganized tasks into. The other is the separation of org and orgzly files in order to ensure the org file tree remains clean and protected from any unfortunate circumstances. This separation also allows one to maintain their org files in a version control management system without any conflicts with use of Dropbox.

Point of information: The Dropbox API does implement it’s own form of version control management in order to prevent file conflicts and loss of information within it’s internal network. It is this internal version control management system that is often the cause of problems when newly created file content is overwritten and/or lost. This is the benefit of using a direct upload approach to managing files on the Dropbox platform. Updates are instantaneous and take priority.

The default configuration variables are as follows:

OptionDefaultDefinitions
app_keyChange ThisDropbox API App Key
app_secretChange ThisDropbox API APP Secret
create_missingTrueCreate any missing files from configuration
backupTrueBackup original org files
split_eventsTruePlace events in seperate events file
dropbox_folder/orgzlyName of folder for orgzly in dropbox
resource_folder"~/orgzly/Resources"Folder where solely attachment files will be stored
org_files"~/org/todo.org", "~/org/inbox.org"Comma seperated list of org files to process entries/nodes from.
orgzly_files"~/orgzly/todo.org", "~/orgzly/inbox.org"Comma seperated orgzly file list to use with this entire system
org_inbox"~/org/inbox.org"Name of org mode inbox file to push new or changed entries to
orgzly_inbox"~/orgzly/inbox.org"Name of orgzly inbox to add new or changed entries to
org_events"~/org/events.org"Name of file containing events for org
orgzly_events"~/orgzly/events.org"Name of file containing events for orgzly
days7Number of days to draw entries / nodes for
todos"TODO", "LATERS", "HOLD", "OPEN"Org “TODO” keywords defining an uncomplete task
dones"DONE", "CLOSED", "CANCELED"Org “DONE” keywords defining a complete task

Note: The actual values are not enclosed in double quotation marks. This is solely done for the formatting of this file.

For redundancy, the configuration file spec is as follows:

app_key = string(default='Replace with your dropbox app key')
app_secret = string(default='Replace with your dropbox app secret')
create_missing = boolean(default=True)
backup = boolean(default=True)
split_events = boolean(default=True)
dropbox_folder = string(default='orgzly')
resources_folder = string(default='~/orgzly/Resources')
org_files = list(default=list('~/org/todo.org'))
orgzly_files = list(default=list('~/orgzly/todo.org'))
org_inbox = string(default='~/org/inbox.org')
orgzly_inbox = string(default='~/orgzly/inbox.org')
org_events = string(default='~/org/events.org')
orgzly_events = string(default='~/orgzly/events.org')
days = integer(default=7)
todos = list(default=list('TODO', 'LATERS', 'HOLD', 'OPEN'))
dones = list(default=list('DONE', 'CLOSED', 'CANCELED'))

Usage:

Please note! In order to avoid either a file conflict error or a overall general buggering of org files, “overwrite mode” has been enabled for dropbox api.

Any of the following methods may be employed to run this script:

  • Navigate to the repository directory and run python org-orgzly.py
  • create an alias in your shell rc file
  • create a simple script in your $PATH that points to the repository and run it where ever
  • for the reckless cron could be employed to run this script periodically

All should work since things are kept together in a single file. An example of creating an alias for ZSH or Bash is below:

alias org-orgzly="/path/to/python /path/to/org-orgzly/org-orgzly.py"

Below are the four commands available for org-orgzly. See workflow below for instructions on what order to execute them.

Command FlagsWhat they do
--helpPrints Help information
--versionSpits out script version number
--dropbox_tokenFetches initial dropbox access token
--config(optional) Path to configuration file if different from default
--listList remote contents of Dropbox:/orgzly/
--upCombines --push and --put, in that order
--downCombines --get and --pull, in that order
--pushParses org files and copies entries matching parameters to orgzly inbox
--pullCopies newly created entries in orgzly inbox to your og inbox
--putUploads orgzly to Dropbox
--getDownloads orgzly files from Dropbox

The intention of the above “flag commands” is for them to run individually, and for the most part this is required, as not doing so could be very messy and lead to data loss. The intended command flow is as follows.

Recommended Workflow

  • Use --up to parse org nodes and move them to dropbox.
  • Retrieve entries from orgzly with --down.

Sequence of Operation

  1. --up:
    1. --push: Push to orgzly
    2. --put: Put in Dropbox
  2. --down:
    1. --get: Get from Dropbox
    2. --pull: Pull from orgzly

Process Diagrams

./Resources/README/sequence.svg

./Resources/README/up.svg

./Resources/README/down.svg

./Resources/README/flow.png

Recent Changes

A Note on Attachments

As a new experimental feature, modifications have been made to allow the upload of attachment files located within the designated attachment folder, referred to as “resource folder”. By default this folder is located inside the orgzly directory and will rather uncreatively be named “Resources”. If this folder does not exist, it will be created for you as a part of the normal file checking process. If this folder does not exist remotely on dropbox, it will also be created for you when asked to put files in Dropbox.

Configuration file changes

To facilitate the new feature additions, additional configuration variables were added to the configuration file. If you are using version =<0.0.8= (less than eight), these variables must be added to the configuration file manually, or if desired, you can completely delete your configuration file and have org-orgzly create another one for you with the default configuration variables.

These changes are substantial enough to warrant avoidance of listing them here seperately. It is advised for the user to review the configuration variables table above and compare it to their own configuration file to discover what these variables are, and where do they need to be placed in the configuration file.

If you fail to perform the modification of your configuration file, the script will become very crossed with you, and refuse to run.

Attachment folder requirements

Some org-mode extensions naturally, by default, create a subfolder inside of the Resource folder with the same title as the org_file the attachment is being added to. For example, a file attached to inbox.org will be copied into Resources/inbox. This will need to be changed in order to upload attachments to Dropbox using this script. Rather that attachments being placed in a subfolder, all attachments must be placed solely in the resources folder without the creation of subfolders. Creating subfolders in the resources folder will cause the script to fail, because folders cannot be uploaded to dropbox, they must be created first and only then can all the files be uploaded to the newly created folder.

Resources sync back

The attachment folder or “resources” now syncs all the way back to your “org” directory.

Now with ascii art

Ascii art has been added to the project by facilitation of the python art package.

Troubleshooting

As long as the option create_missing is set to True, any missing file defined in the configuration file will be automatically created for the user in the defined folder located in the user’s home directory. The file will be created with a basic #+TITLE and #+DATE heading.

The script automatically creates backup files for the user in order to prevent crucial data loss. Those files can be found in the .backup directory located in their orgzly folder.

If you encounter any issues or bugs, please feel free to submit an issue for assistance. If there are also any desired feature requests, you may also fill out an issue labeling it as a “Feature Request”.

Dropbox App Creation and Credentials

Creating a new dropbox app is not that difficult as long as you have a preexisting Dropbox account. All you need to do is [login to Dropbox](https://www.dropbox.com/login “Dropbox Login”) browse over to the [Dropbox developers site](https://developers.dropbox.com/ “Dropbox Developers”) and click the App Console button located in the top right corner of the site. From there you will see a list of all apps you have created, if you have created any previously. Under the drop down menu of your Dropbox Name, and to the right of the title “My Apps”, you will see a bright blue button labeled “Create app”. Click it, and then create your app by filling out the required parts.

  1. You will only be allowed to choose the “Scoped access” API, so select it.
  2. Next it will ask what type of access you need. Select, “App Folder” for better security.
  3. Lastly on this page, it will ask for you to provide a name. Whatever name you choose, it must not contain the phrase “dropbox”. Once done, click the “Create app” button.
  4. Before you write down your App key and secret, there is some extra configuration required.
  5. Select the “Permissions” tab, and make sure the following boxes are checked to enable the correct permissions.
- [x] files.metadata.write
- [x] files.metadata.read
- [x] files.content.write
- [x] files.content.read

Without these selected, the app will not be able to upload and download Dropbox files.

  1. Once complete, click on the “submit” button located in the middle-bottom of your screen.
  2. You know can return to the “Settings” page and write down your app key and app secret for use in the script.

Thanks to the following

This application is dedicated to Karlicoss to whom without it would have never been possible. All the credit goes to the python orgparse library that allows parsing org files in python.

And, of course, thanks goes out to the Org Mode, who have diligently maintained the most brilliant organizational systems ever.

About

A simple python script to parse desired org file(s) entries by specified parameters and generate a file to sync with orgzly.

Topics

Resources

Stars

Watchers

Forks

Languages