___ ___ _
/ _ \ _ _ __ _ ___ / _ \ _ _ __ _ __| |_ _
| (_) | '_/ _` |___| (_) | '_/ _` |_ / | || |
\___/|_| \__, | \___/|_| \__, /__|_|\_, |
|___/ |___/ |__/
A python application to parse and generate org files for orgzly practically, by making managing your org schedule easier.
Please see the heading below concerning integration of attachments and event files for details.
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.
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.
- 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
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.
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.
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.
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.
- orgparse
- configobj
- validate
- art
- dropbox
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:
| Option | Default | Definitions |
|---|---|---|
| app_key | Change This | Dropbox API App Key |
| app_secret | Change This | Dropbox API APP Secret |
| create_missing | True | Create any missing files from configuration |
| backup | True | Backup original org files |
| split_events | True | Place events in seperate events file |
| dropbox_folder | /orgzly | Name 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 |
| days | 7 | Number 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'))
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
rcfile - create a simple script in your
$PATHthat 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 Flags | What they do |
|---|---|
--help | Prints Help information |
--version | Spits out script version number |
--dropbox_token | Fetches initial dropbox access token |
--config | (optional) Path to configuration file if different from default |
--list | List remote contents of Dropbox:/orgzly/ |
--up | Combines --push and --put, in that order |
--down | Combines --get and --pull, in that order |
--push | Parses org files and copies entries matching parameters to orgzly inbox |
--pull | Copies newly created entries in orgzly inbox to your og inbox |
--put | Uploads orgzly to Dropbox |
--get | Downloads 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.
- Use
--upto parse org nodes and move them to dropbox. - Retrieve entries from orgzly with
--down.
--up:--push: Push to orgzly--put: Put in Dropbox
--down:--get: Get from Dropbox--pull: Pull from orgzly
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.
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.
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.
The attachment folder or “resources” now syncs all the way back to your “org” directory.
Ascii art has been added to the project by facilitation of the python art package.
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”.
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.
- You will only be allowed to choose the “Scoped access” API, so select it.
- Next it will ask what type of access you need. Select, “App Folder” for better security.
- 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.
- Before you write down your App key and secret, there is some extra configuration required.
- 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.
- Once complete, click on the “submit” button located in the middle-bottom of your screen.
- You know can return to the “Settings” page and write down your app key and app secret for use in the script.
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.