{"id":20837810,"url":"https://github.com/anoduck/org-orgzly","last_synced_at":"2025-05-08T20:29:49.073Z","repository":{"id":61711399,"uuid":"543373124","full_name":"anoduck/org-orgzly","owner":"anoduck","description":"A simple python script to parse desired org file(s) entries by specified parameters and generate a file to sync with orgzly.","archived":false,"fork":false,"pushed_at":"2023-04-04T23:30:44.000Z","size":926,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-31T17:59:02.595Z","etag":null,"topics":["org-mode","orgmode","orgzly"],"latest_commit_sha":null,"homepage":"https://codeberg.org/anoduck/org-orgzly","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anoduck.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-30T00:41:14.000Z","updated_at":"2024-11-08T13:02:25.000Z","dependencies_parsed_at":"2023-02-17T02:31:52.471Z","dependency_job_id":null,"html_url":"https://github.com/anoduck/org-orgzly","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoduck%2Forg-orgzly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoduck%2Forg-orgzly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoduck%2Forg-orgzly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoduck%2Forg-orgzly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anoduck","download_url":"https://codeload.github.com/anoduck/org-orgzly/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253144316,"owners_count":21861036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["org-mode","orgmode","orgzly"],"created_at":"2024-11-18T01:08:39.296Z","updated_at":"2025-05-08T20:29:49.033Z","avatar_url":"https://github.com/anoduck.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"#+TITLE: Org-Orgzly\n#+DATE: Tue Nov  8 02:56:53 2022\n#+AUTHOR: Anoduck\n\n#+NAME: org-orgzly_logo.png\n[[./Resources/README/org-orgzly_logo.png]]\n\n#+begin_src text\n  ___                ___              _\n / _ \\ _ _ __ _ ___ / _ \\ _ _ __ _ __| |_  _\n| (_) | '_/ _` |___| (_) | '_/ _` |_ / | || |\n \\___/|_| \\__, |    \\___/|_| \\__, /__|_|\\_, |\n          |___/              |___/      |__/\n\n#+end_src\n* Org-orgzly\n/A python application to parse and generate org files for orgzly practically, by making managing your org schedule easier./\n*** New Breaking Changes - Dec 03 2022\nPlease see the heading below concerning integration of attachments and event files for details.\n*** Issues/Bugs?\nIf you experience ANY issues using this script, encounter ANY bugs, or you just think this script sucks. PLEASE, submit and issue to\neither the github or codeberg repositories, and we will try our best to address the issue as soon as feasibly possible.\n*** About\n**** What it does\nThis script takes a specified list of org files, extracts org entries, filters out entries that do not meet specified TODO and Date\nparameters, provides allowances for days in a month and leap years, and then writes those entries to the designated orgzly inbox. It\nthen uploads designated orgzly files to Dropbox. Then later on, the user may download those files from Dropbox, and merge entries\nfrom the orgzly inbox back to org via the org inbox file.\n**** Features\n- Processes org nodes for only a particularly defined amount of days, and add them to your orgzly inbox.\n- Allows for retrieving created org nodes inside your orgzly inbox to your org inbox.\n- Compensates for leap years.\n- Uploads orgzly files to a defined folder in your dropbox account\n- Downloads orgzly files to a defined local folder on your local machine.\n- Lists contents of the remote orgzly folder within dropbox\n- Eleminates duplicate entries\n**** Methodological Assumptions\nThere are several assumptions made concerning time management and the use of orgzly.\n- Evidently orgzly was never intended to be a replacement for emacs.\n- The user does not desire to sync all org agenda files with orgzly.\n- Mobile management of many org entries is difficult.\n- Duplicate org entries are not cool.\n- Only having a few entries covering the immediate future is all that is needed.\n*** What is required\nAdmittedly, there are many limitations to the application, so don't go all willy nilly on it. In order for the program to discover and\nuse your nodes, you will need to use a todo keyword, and either a deadline or a scheduled date. Traversal of multileveled org entries\nshould be capable, due to the script processing all entries that possess the previously required properties.\n**** Installation\nSince in order to make use of this library it is assumed one has reasonable apprehension of EMACS use, is\nfamiliar with using git, and knows how to execute a python script inside shell.\n**** Preferred installation method\nIt would be to the user's benefit to clone the source directly from the repository using\n~git clone https://codeberg.org/anoduck/org-orgzly~. As, this would provide the user with the most recent\nversion of the script with all newly added features. Please consider the releases as existing for historical\nnotation.\n**** Required Python libraries\n- orgparse\n- configobj\n- validate\n- art\n- dropbox\n**** The 'ini' file\nThe configuration file, =config.ini= will be automatically generated for you in your ~XDG_CONFIG_HOME~ directory under the =org-orgzly=\nfolder, with the default values already filled out for you. If you plan on using this script in conjunction with\nthe Dropbox service, then you will need to change the values of =app_key= and =app_secret= respectively with\nthe values corresponding to the app your created in the dropbox [[https://www.dropbox.com/developers/apps?_tk=pilot_lp\u0026_ad=topbar4\u0026_camp=myapps][Dropbox App Console]]. More information can be found out concerning the\ndropbox api below.\n\nAll configuration values are *REQUIRED*, and although they do provide the user to customize the script, there are some systematic\nimplementations that must be accommodated in facilitation of your org-task management system. Most notably is the implementation of an\n=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\nfile tree remains clean and protected from any unfortunate circumstances. This separation also allows one to maintain their org files\nin a version control management system without any conflicts with use of Dropbox.\n\n/Point of information:/ The Dropbox API does implement it's own form of version control management in order to prevent file conflicts\nand loss of information within it's internal network. It is this internal version control management system that is often the cause of\nproblems when newly created file content is overwritten and/or lost. This is the benefit of using a direct upload approach to managing\nfiles on the Dropbox platform. Updates are instantaneous and take priority.\n\nThe default configuration variables are as follows:\n\n| Option          | Default                                     | Definitions                                                      |\n|-----------------+---------------------------------------------+------------------------------------------------------------------|\n| app_key         | =Change This=                               | Dropbox API App Key                                              |\n| app_secret      | =Change This=                               | Dropbox API APP Secret                                           |\n| create_missing  | =True=                                      | Create any missing files from configuration                      |\n| backup          | =True=                                      | Backup original org files                                        |\n| split_events    | =True=                                      | Place events in seperate events file                             |\n| dropbox_folder  | =/orgzly=                                   | Name of folder for orgzly in dropbox                             |\n| resource_folder | =\"~/orgzly/Resources\"=                      | Folder where solely attachment files will be stored              |\n| org_files       | =\"~/org/todo.org\", \"~/org/inbox.org\"=       | Comma seperated list of org files to process entries/nodes from. |\n| orgzly_files    | =\"~/orgzly/todo.org\", \"~/orgzly/inbox.org\"= | Comma seperated orgzly file list to use with this entire system  |\n| org_inbox       | =\"~/org/inbox.org\"=                         | Name of org mode inbox file to push new or changed entries to    |\n| orgzly_inbox    | =\"~/orgzly/inbox.org\"=                      | Name of orgzly inbox to add new or changed entries to            |\n| org_events      | =\"~/org/events.org\"=                        | Name of file containing events for org                           |\n| orgzly_events   | =\"~/orgzly/events.org\"=                     | Name of file containing events for orgzly                        |\n| days            | =7=                                         | Number of days to draw entries / nodes for                       |\n| todos           | =\"TODO\", \"LATERS\", \"HOLD\", \"OPEN\"=          | Org \"TODO\" keywords defining an uncomplete task                  |\n| dones           | =\"DONE\", \"CLOSED\", \"CANCELED\"=              | Org \"DONE\" keywords defining a complete task                     |\n*Note:* The actual values are not enclosed in double quotation marks. This is solely done for the formatting of this file.\n\nFor redundancy, the configuration file spec is as follows:\n\n#+begin_src conf\n  app_key = string(default='Replace with your dropbox app key')\n  app_secret = string(default='Replace with your dropbox app secret')\n  create_missing = boolean(default=True)\n  backup = boolean(default=True)\n  split_events = boolean(default=True)\n  dropbox_folder = string(default='orgzly')\n  resources_folder = string(default='~/orgzly/Resources')\n  org_files = list(default=list('~/org/todo.org'))\n  orgzly_files = list(default=list('~/orgzly/todo.org'))\n  org_inbox = string(default='~/org/inbox.org')\n  orgzly_inbox = string(default='~/orgzly/inbox.org')\n  org_events = string(default='~/org/events.org')\n  orgzly_events = string(default='~/orgzly/events.org')\n  days = integer(default=7)\n  todos = list(default=list('TODO', 'LATERS', 'HOLD', 'OPEN'))\n  dones = list(default=list('DONE', 'CLOSED', 'CANCELED'))\n#+end_src\n*** Usage:\n*Please note!* In order to avoid either a file conflict error or a overall general buggering of org files, \"overwrite mode\" has been\nenabled for dropbox api.\n\nAny of the following methods may be employed to run this script:\n- Navigate to the repository directory and run ~python org-orgzly.py~\n- create an alias in your shell =rc= file\n- create a simple script in your ~$PATH~ that points to the repository and run it where ever\n- for the reckless cron could be employed to run this script periodically\n\nAll should work since things are kept together in a single file. An example of creating an alias for ZSH or Bash is below:\n\n#+begin_src bash\n\nalias org-orgzly=\"/path/to/python /path/to/org-orgzly/org-orgzly.py\"\n\n#+end_src\n\nBelow are the four commands available for org-orgzly. See _workflow_ below for instructions on what order to execute them.\n\n| Command Flags     | What they do                                                            |\n|-------------------+-------------------------------------------------------------------------|\n| ~--help~          | Prints Help information                                                 |\n| ~--version~       | Spits out script version number                                         |\n| ~--dropbox_token~ | Fetches initial dropbox access token                                    |\n| ~--config~        | (optional) Path to configuration file if different from default         |\n| ~--list~          | List remote contents of =Dropbox:/orgzly/=                              |\n| ~--up~            | Combines =--push= and =--put=, in that order                            |\n| ~--down~          | Combines =--get= and =--pull=, in that order                            |\n| ~--push~          | Parses org files and copies entries matching parameters to orgzly inbox |\n| ~--pull~          | Copies newly created entries in orgzly inbox to your og inbox           |\n| ~--put~           | Uploads orgzly to Dropbox                                               |\n| ~--get~           | Downloads orgzly files from Dropbox                                     |\n\nThe intention of the above \"flag commands\" is for them to run individually, and for the most part this is required, as not doing so\ncould be very messy and lead to data loss. The intended command flow is as follows.\n**** Recommended Workflow\n- Use ~--up~ to parse org nodes and move them to dropbox.\n- Retrieve entries from orgzly with ~--down~.\n**** Sequence of Operation\n1. ~--up~:\n   1. ~--push~: Push to orgzly\n   2. ~--put~: Put in Dropbox\n   \n2. ~--down~:\n   1. ~--get~: Get from Dropbox\n   2. ~--pull~: Pull from orgzly\n\n**** Process Diagrams\n#+NAME: sequence.svg\n[[./Resources/README/sequence.svg]]\n\n#+NAME: up.svg\n[[./Resources/README/up.svg]]\n\n#+NAME: down.svg\n[[./Resources/README/down.svg]]\n\n#+NAME: plantuml.svg\n[[./Resources/README/flow.png]]\n\n*** Recent Changes\n**** A Note on Attachments\nAs a new experimental feature, modifications have been made to allow the upload of attachment files located within the designated\nattachment folder, referred to as \"resource folder\". By default this folder is located inside the orgzly directory and will rather\nuncreatively be named \"Resources\". If this folder does not exist, it will be created for you as a part of the normal file checking\nprocess. If this folder does not exist remotely on dropbox, it will also be created for you when asked to put files in Dropbox.\n**** Configuration file changes\nTo facilitate the new feature additions, additional configuration variables were added to the configuration file. *If you are\nusing version =\u003c0.0.8= (less than eight), these variables must be added to the configuration file manually*, or if desired, you can\ncompletely delete your configuration file and have org-orgzly create another one for you with the default configuration variables.\n\nThese changes are substantial enough to warrant avoidance of listing them here seperately. It is advised for the user to review the\nconfiguration variables table above and compare it to their own configuration file to discover what these variables are, and where do\nthey need to be placed in the configuration file.\n\nIf you fail to perform the modification of your configuration file, the script will become very crossed with you, and refuse to run.\n***** Attachment folder requirements\nSome org-mode extensions naturally, by default, create a subfolder inside of the Resource folder with the same title as the org_file\nthe attachment is being added to. For example, a file attached to ~inbox.org~ will be copied into ~Resources/inbox~. This will\nneed to be changed in order to upload attachments to Dropbox using this script. Rather that attachments being placed in a subfolder,\n*all attachments must be placed solely in the resources folder without the creation of subfolders*. Creating subfolders in the resources\nfolder will cause the script to fail, because folders cannot be uploaded to dropbox, they must be created first and only then can all\nthe files be uploaded to the newly created folder.\n***** Resources sync back\nThe attachment folder or \"resources\" now syncs all the way back to your \"org\" directory.\n***** Now with ascii art\nAscii art has been added to the project by facilitation of the python art package.\n*** Troubleshooting\nAs long as the option =create_missing= is set to =True=, any missing file defined in the configuration file\nwill be automatically created for the user in the defined folder located in the user's home directory. The file will be created with a\nbasic ~#+TITLE~ and ~#+DATE~ heading.\n\nThe script automatically creates backup files for the user in order to prevent crucial data loss. Those files\ncan be found in the ~.backup~ directory located in their orgzly folder.\n\nIf you encounter any issues or bugs, please feel free to submit an issue for assistance. If there are also\nany desired feature requests, you may also fill out an issue labeling it as a \"Feature Request\".\n*** Dropbox App Creation and Credentials\nCreating a new dropbox app is not that difficult as long as you have a preexisting Dropbox account. All you\nneed to do is [login to Dropbox](https://www.dropbox.com/login \"Dropbox Login\") browse over to the [Dropbox developers\nsite](https://developers.dropbox.com/ \"Dropbox Developers\") and click the =App Console= button located in the top right corner of the\nsite. 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\nDropbox Name, and to the right of the title \"My Apps\", you will see a bright blue button labeled \"Create app\". Click it, and then\ncreate your app by filling out the required parts.\n\n1. You will only be allowed to choose the \"Scoped access\" API, so select it.\n2. Next it will ask what type of access you need. Select, \"App Folder\" for better security.\n3. 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.\n4. Before you write down your App key and secret, there is some extra configuration required.\n5. Select the \"Permissions\" tab, and make sure the following boxes are checked to enable the correct\n   permissions.\n#+begin_example\n   - [x] files.metadata.write\n   - [x] files.metadata.read\n   - [x] files.content.write\n   - [x] files.content.read\n#+end_example\nWithout these selected, the app will not be able to upload and download Dropbox files.\n6. Once complete, click on the \"submit\" button located in the middle-bottom of your screen.\n7. You know can return to the \"Settings\" page and write down your app key and app secret for use in the\n   script.\n*** Thanks to the following\nThis application is dedicated to [[https://github.com/karlicoss][Karlicoss]] to whom without it would have never been possible. All the\ncredit goes to the [[https://github.com/karlicoss/orgparse][python orgparse library]] that allows parsing org files in python.\n\nAnd, of course, thanks goes out to the [[https://orgmode.org/][Org Mode]], who have diligently maintained the\nmost brilliant organizational systems ever.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoduck%2Forg-orgzly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanoduck%2Forg-orgzly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoduck%2Forg-orgzly/lists"}