khalorg 0.0.0__tar.gz

khalorg-0.0.0/.gitignore

@@ -0,0 +1,11 @@
+*.egg-info
+*.mkv
+*.shada
+*.vim
+*.vscode
+*venv*
+__pycache__
+build
+davmail.log
+dist
+stubs

khalorg-0.0.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog - Khalorg
+This document describes the changes that were made to the software for each
+version. The changes are described concisely, to make it comprehensible for the
+user. A change is always categorized based on the following types:
+- Bug: a fault in the software is fixed.
+- Feature: a functionality is added to the program.
+- Improvement: a functionality in the software is improved.
+- Task: a change is made to the repository that has no effect on the source
+code.
+
+# 0.0.0
+
+## Feature
+- `khalorg new` is added. It converts an org agenda item into a `khal` agenda
+item.
+- `khalorg list` is added. It converts a `khal` agenda item into an org agenda
+item.
+- `khalorg edit` is added. It edits an existing `khal` agenda item with org
+mode.
+- `khalorg delete` is added. It deletes an existing `khal` item.
+- Recurring items are supported by providing an org repeater in the
+time stamp (e.g., `+1w`). The following is supported:
+  - the follow org repeaters: `+{integer}{d,w,m,y}`
+  - `khalorg new` and `khalorg edit --edit-dates` support 1 time stamp
+  per org agenda item.
+  - `khalorg list` concatenates timestamps that cannot be describes by
+  an org repeater, resulting in an org agenda item with multiple
+  timestamps.
+  - Supports an `until` date for recurring items. The until date can be
+  supplied through an org property `UNTIL`.
+
+## Task
+- An Office 365 workflow with a [bash script](./extras/calsync) is added which
+synchronizes all `vdirsyncer` calendars and exports them to org with `khalorg`.
+Davmail is used as the CalDav server. 

khalorg-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to khalorg
+
+Thank you for considering contributing to the `khalorg` project! We welcome contributions from everyone.
+
+## Getting Started
+
+1. Fork the repository on GitHub.
+2. Clone your forked repository (`git clone https://github.com/your_username/khalorg.git`).
+3. Create a new branch (`git checkout -b my_branch_name`).
+4. Make your changes.
+5. Commit your changes (`git commit -am "Add some feature"`).
+6. Push your changes to your forked repository (`git push origin my_branch_name`).
+7. Create a pull request on GitHub.
+
+## Code of Conduct
+
+Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
+
+## Reporting Bugs
+
+If you encounter any bugs or issues, please report them on the issue tracker at:
+
+[Issues](https://github.com/username/khalorg/issues)
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the MIT License.
+
+

khalorg-0.0.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 BartSte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

khalorg-0.0.0/PKG-INFO

@@ -0,0 +1,422 @@
+Metadata-Version: 2.1
+Name: khalorg
+Version: 0.0.0
+Summary: An interface between Org mode and Khal cli calendar.
+Author: BartSte
+License: MIT License
+Keywords: khal,org mode,vdirsyncer,CalDav,agenda,emacs,neovim,orgmode-nvim
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: debug
+Provides-Extra: test
+Provides-Extra: build
+License-File: LICENCE
+
+[Click here for the GitHub page.](https://github.com/BartSte/khalorg) 
+
+# Contents
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Neovim plugin](#neovim-plugin)
+- [Workflow for Office 365](#workflow-for-office-365)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Improvements](#improvements)
+
+# Introduction
+`khalorg` is an interface between Org mode and Khal cli calendar.
+
+## Definitions
+- [CalDav](<https://en.wikipedia.org/wiki/CalDAV>): internet standard for client access to calendars
+- [Davmail](<https://davmail.sourceforge.net/e>): CalDav exchange gateway
+- [khal](<https://github.com/pimutils/khal>): command line calendar app 
+- [khalel](<https://gitlab.com/hperrey/khalel>): interface between emacs and khal
+- [nvim-orgmode](<https://github.com/nvim-orgmode/orgmode>): org mode for neovim
+- [org](<https://orgmode.org>): plain text system for keeping notes, agendas and more
+- [vdirsyncer](<https://github.com/pimutils/vdirsyncer>): synchronizes calendars and addressbooks between servers and the local file system
+
+## Motivation
+I use org mode to manage my agenda and my notes. However, in a professional
+setting, you are often required to use proprietary software for your agenda,
+like Office 365. Luckily, programs exist that can synchronize agendas from
+different sources, by implementing the CalDav standard. Personally, I like to
+use `vdirsyncer` with `khal` to synchronize my agendas. To bridge the gap
+between `khal` and `org mode`, only 1 program exists called: `khalel`. However,
+this program is designed for `emacs`. Since there are also org mode users
+outside of `emacs` (e.g. `neovim`), `khalorg` aims to be a general interface
+between `vdirsyncer`/`khal` and `org mode`.
+
+Based on the above, the following workflow is desired:
+
+``` example
+┌──────┐     
+│CalDav│     
+└┬─────┘     
+┌▽─────────┐  
+│vdirsyncer│  
+└┬─────────┘  
+┌▽───┐        
+│khal│        
+└┬───┘        
+┌▽───────┐
+│khalorg │
+└┬───────┘
+┌▽───────┐    
+│org mode│    
+└────────┘    
+```
+
+## Features
+- [x] Can be used by org mode for emacs, vim and neovim.
+- [x] Vdirsyncer calendars can be manipulated by using the cli of `khal`
+  as the interface.
+- [x] `khalorg new`: convert an org agenda item into a `khal` agenda
+  item.
+- [x] `khalorg list`: convert a `khal` agenda item into an org agenda
+  item.
+- [x] `khalorg edit`: edit an existing `khal` agenda item with org mode.
+- [x] `khalorg delete`: delete an existing `khal` item.
+- [x] Recurring items are supported by providing an org repeater in the
+  time stamp (e.g., `+1w`). The following is supported:
+  - the follow org repeaters: `+{integer}{d,w,m,y}`
+  - `khalorg new` and `khalorg edit --edit-dates` support 1 time stamp
+    per org agenda item.
+  - `khalorg list` concatenates timestamps that cannot be describes by
+    an org repeater, resulting in an org agenda item with multiple
+    timestamps.
+  - Supports an `until` date for recurring items. The until date can be
+    supplied through an org property `UNTIL`.
+- [x] Has unittests
+- [x] Includes an Office 365 workflow with a bash script
+- [x] Semantic versioning
+- [x] Gifs with demos
+- [x] Neovim plugin
+- [x] Is available on PyPI
+
+# Installation
+For safety, always make a back-up of your calendar before installing software
+that is new to you.
+
+Make sure your `khal` date format is compatible with org, otherwise it
+will not work. When running `khal printformats` you should get:
+``` example
+longdatetimeformat: 2013-12-21 Sat 21:45
+datetimeformat: 2013-12-21 Sat 21:45
+longdateformat: 2013-12-21 Sat
+dateformat: 2013-12-21 Sat
+timeformat: 21:45
+```
+If not, check the documentation of `khal` on how to change this.
+
+## PyPi
+Install by running the following command:
+``` bash
+pip install khalorg
+```
+
+## From source
+Set your current working directory to the root directory, i.e, the
+directory containing the `pyproject.toml` file. Next, run:
+
+``` bash
+pip install .
+```
+After this, the executable `khalorg` will be available.
+
+## For development
+If you want to develop the code, debug it, and test it, run:
+``` bash
+pip install -e '.[test,debug]'
+```
+
+# Usage
+Use `khalorg --help` to get information about the cli of `khalorg`. The
+following section discuss the `khalorg` commands that are available.
+
+## List: from khal to org
+
+![khalorg list demo](https://github.com/BartSte/khalorg/blob/main/demo/list.gif?raw=true)
+
+Agenda items from `khal` can be converted to org items using the
+`khalorg list` command. For examples:
+
+``` bash
+khalorg list my_calendar today 90d > my_calendar.org 
+```
+
+Here, the `khal` agenda items of the calendar `my_calendar` are
+converted to org format and written to a file called `my_calendar.org`.
+The range is specified from `today` till `90d` (90 days) in the future.
+For more information about the allowed date formats, check the
+`khal list` command, which is used for this functionality. It is assumed
+that the `khal` calendar called `my_calendar` exists. Make sure
+`my_calendar` is a calendar that exists on your local file system.
+
+### –format
+If `khalorg list --format` option is not defined, the default one is
+used which can be found at `./khalorg/static/khalorg_format.txt`. If you
+want to define your own format, you have 2 options: you can use the
+`khalorg list --format` option, or you can place your custom format at
+`$HOME/.config/khalorg/khalorg_format.txt` this format will then be used
+instead of the default one that is shown below.
+
+``` org
+* {title}
+  {timestamps}
+  :PROPERTIES:
+  :ATTENDEES: {attendees}
+  :CALENDAR: {calendar}
+  :CATEGORIES: {categories}
+  :LOCATION: {location}
+  :ORGANIZER: {organizer}
+  :STATUS: {status}
+  :UID: {uid}
+  :URL: {url}
+  :END:
+  {description}
+```
+
+the following keys are supported:
+- `{attendees}`: a comma separated list of email addresses of attendees
+- `{calendar}`: the name of the khal calendar
+- `{categories}`: the categories property of the item
+- `{description}`: the description of the item
+- `{location}`: the location of the item
+- `{organizer}`: the email of the organizer
+- `{status}`: the status of the item, e.g., TENTATIVE or ACCEPTED
+- `{timestamps}`: the timestamp of the item
+- `{title}`: the summary of the item
+- `{uid}`: the UID of the item
+- `{rrule_until}`: the until value of the RRULE.
+- `{url}`: the url property
+
+the following keys are supported but are typically reserved for internal use
+and are therefore less informative:
+
+- `{until}`: the until property value. Is empty when using `khalorg list`.
+- `{rrule}`: the ICal RRULE of the item.
+
+### Recurring items
+
+The `khalorg list` command relies on the `khal list` command. Using this
+command the `RRULE` of each item is retrieved to created the correct org
+repeater. Only simple org repeaters are supported that have the
+following form: `+[number][h,w,m,y]`. Complex `RRULEs` are described by
+concatenating the corresponding timestamps within 1 agenda item,
+resulting in a list of items. For example, the agenda item below
+represents a weekly recurring event where the first meeting was moved to
+another date, resulting in a timestamp without a repeater, and one with
+a repeater.
+
+``` org
+* Meeting
+  <2023-01-05 Thu 01:00-02:00>
+  <2023-01-08 Sun 01:00-02:00 +1w>
+  :PROPERTIES:
+  :UID: 123
+  :LOCATION: Somewhere
+  :ORGANIZER: Someone (someone@outlook.com)
+  :ATTENDEES: test@test.com, test2@test.com
+  :URL: www.test.com
+  :END:
+  Hello,
+  
+  Lets have a meeting.
+  
+  Regards,
+  
+  
+  Someone
+```
+
+## New: from org to khal
+
+![khalorg new demo](https://github.com/BartSte/khalorg/blob/main/demo/new.gif?raw=true)
+
+An org agenda item can be converted to a new `khal` agenda item by
+feeding the org item through stdin to `khalorg new` and specifying the
+khal calendar name as a positional argument. For example, the consider
+the org item below, which is saved as `meeting.org`.
+
+``` org
+* Meeting
+  <2023-01-01 Sun 01:00-02:00 +1w>
+  :PROPERTIES:
+  :UID: 123
+  :LOCATION: Somewhere
+  :ORGANIZER: Someone (someone@outlook.com)
+  :ATTENDEES: test@test.com, test2@test.com
+  :URL: www.test.com
+  :END:
+  Hello,
+  
+  Lets have a meeting.
+  
+  Regards,
+  
+  
+  Someone
+```
+
+This item can be converted to the `khal` calendar called
+"my<sub>calendar</sub>" as follows:
+
+``` bash
+cat meeting.org | khalorg new my_calendar
+```
+
+It is assumed that the `khal` calendar called "my<sub>calendar</sub>"
+exists. Make sure "my<sub>calendar</sub>" is a calendar that exists on
+your local file system.
+
+### Recurring items
+Only 1 timestamp per org item is supported. Note that the meeting above
+is repeated every week (`+1w`). Only simple org repeaters are supported
+that have the following form: `+[number][h,w,m,y]`. These events repeat
+forever, unless you specify an end date using the \`UNTIL\` property in
+the org file.
+
+Personally, when I need to create a complex repeat pattern (or when I
+need outlook specific items like a Teams invite), I create the event in
+outlook first. Next, I use `khalorg edit` to change the fields that need
+editing (e.g., the description).
+
+### Attendees
+Optionally, attendees can be added to the `ATTENDEES` property field.
+The attendees will be added to the `Attendees` field of `khal`. Once you
+synchronize `khal` with a server (e.g., outlook) an invitation will be
+send to the attendees.
+
+## Edit: from org to khal
+
+![khalorg edit demo](https://github.com/BartSte/khalorg/blob/main/demo/edit.gif?raw=true)
+
+Existing `khal` events can be updates by feeding an org file with the
+corresponding UID through stdin to the `khalorg edit` command. For
+example, the org agenda item of <span class="spurious-link"
+target="New">*New*</span> can be altered and used as an input for
+`khalorg edit`, as long as the UID remains untouched.
+
+``` org
+* Edited meeting
+  <2023-01-01 Sun 01:00-02:00 +1w>
+  :PROPERTIES:
+  :UID: 123
+  :ORGANIZER: Someone (someone@outlook.com)
+  :ATTENDEES: other@test.com
+  :END:
+  Hello,
+  
+  I edited the meeting by removing the location and url. I also changed the
+  title and the attendees field.
+  
+  Regards,
+  
+  
+  Someone
+```
+
+Next, run the following command:
+
+``` bash
+cat meeting.org | khalorg edit my_calendar
+```
+
+When using `khalorg edit` please consider the following:
+
+- Editing an existing event is different from creating a new one as the
+  original `icalendar` file is retained. Only parts of it are altered.
+  This is convienent when the icalendar file contains information that
+  cannot be generated by `khalorg`. For example, a Microsoft Team
+  meeting.
+- Only the PROTO event is edited, i.e., the whole series is altered not
+  only the occurence.
+- `khal edit` will only update the dates + recurrence if the
+  `--edit-dates` flag is passed. This avoids editing the start-stop date
+  when editing an event that contains multiple timestamps (which are not
+  supported).
+
+## Delete: from org to khal
+ 
+![khalorg deleted demo](https://github.com/BartSte/khalorg/blob/main/demo/delete.gif?raw=true)
+
+An event can be deleted from a khal calendar by feeding an org file to the
+`khalorg delete` command through stdin. The org file must contain an agenda
+item with a non-empty UID property. For example, the khal event that was
+created using the <span class="spurious-link" target="New">*New*</span> command
+above can be removed by feeding the same file to `khalorg delete`:
+
+``` bash
+cat meeting.org | khalorg delete my_calendar
+```
+
+### Recurring items
+When deleting recurring items the whole series will be removed. Removing
+occurrences is not supported.
+
+## Neovim plugin
+The neovim plugin can be found here: [nvim-khalorg](https://github.com/BartSte/nvim-khalorg).
+
+# Workflow for Office 365
+The diagram below illustrates the workflow than can be achieved when using
+`khalorg`. The folder `extras`, on the
+[GitHub](https://github.com/BartSte/khalorg) page, contains a `bash` script
+called `calsync`, that synchronizes `vdirsyncer` calendars and exports them as
+an org file using the `khalorg list` command. Davmail is used as the CalDav
+server in this specific example.
+
+``` example
+┌──────────┐  
+│Office 365│  
+└┬─────────┘  
+┌▽──────┐     
+│Davmail│     
+└┬──────┘     
+┌▽─────────┐  
+│vdirsyncer│  
+└┬─────────┘  
+┌▽───┐        
+│khal│        
+└┬───┘        
+┌▽───────┐
+│khalorg │
+└┬───────┘
+┌▽───────┐    
+│org mode│    
+└────────┘    
+```
+
+## Troubleshooting
+
+If you encounter any issues, please report them on the issue tracker at:
+[khalorg issues](https://github.com/BartSte/khalorg/issues)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for
+more information.
+
+## License
+
+Distributed under the [MIT License](./LICENCE).
+
+# Improvements:
+- [ ] Timezones are not yet supported, so `khalorg` will only work when
+  you agenda remain in the timezone that you specified within your
+  `khal` config.
+- [ ] Running khal commands directly from a script in not
+  straightforward. Therefore, khal is executed as a subprocess, by using
+  its command line interface.
+- [ ] `khalorg new` and `khal edit` only support 1 timestamp per item.
+  However, it is desired that all timestamps within 1 org agenda item,
+  end up in 1 khal event, as is the case for the `orgagenda`. To achieve
+  this the following could be build:
+  - [ ] When multiple timestamps without an org repeater are provided,
+    find the `RRULE` that describes them. Also, set the `UNTIL` date to
+    the last date. If no `RRULE` can be found, raise an error. Another
+    option could be to use the `RDATE` option of ICal.
+  - [ ] When multiple timestamps with an org repeater are presented, try
+    to find the `RRULE` that describes them.