Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/anoduck/org-orgzly

A simple python script to parse desired org file(s) entries by specified parameters and generate a file to sync with orgzly.
https://github.com/anoduck/org-orgzly

org-mode orgmode orgzly

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
#+TITLE: Org-Orgzly

#+DATE: Tue Nov  8 02:56:53 2022

#+AUTHOR: Anoduck



#+NAME: org-orgzly_logo.png

[[./Resources/README/org-orgzly_logo.png]]



#+begin_src text

  ___                ___              _

 / _ \ _ _ __ _ ___ / _ \ _ _ __ _ __| |_  _

| (_) | '_/ _` |___| (_) | '_/ _` |_ / | || |

 \___/|_| \__, |    \___/|_| \__, /__|_|\_, |

          |___/              |___/      |__/



#+end_src

* 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 [[https://www.dropbox.com/developers/apps?_tk=pilot_lp&_ad=topbar4&_camp=myapps][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:



#+begin_src conf

  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'))

#+end_src

*** 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:



#+begin_src bash



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



#+end_src



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.

**** 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

#+NAME: sequence.svg

[[./Resources/README/sequence.svg]]



#+NAME: up.svg

[[./Resources/README/up.svg]]



#+NAME: down.svg

[[./Resources/README/down.svg]]



#+NAME: plantuml.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.

#+begin_example

   - [x] files.metadata.write

   - [x] files.metadata.read

   - [x] files.content.write

   - [x] files.content.read

#+end_example

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

6. Once complete, click on the "submit" button located in the middle-bottom of your screen.

7. 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 [[https://github.com/karlicoss][Karlicoss]] to whom without it would have never been possible. All the

credit goes to the [[https://github.com/karlicoss/orgparse][python orgparse library]] that allows parsing org files in python.



And, of course, thanks goes out to the [[https://orgmode.org/][Org Mode]], who have diligently maintained the

most brilliant organizational systems ever.