zaloog / kanban-python Goto Github PK

View Code? Open in Web Editor NEW

247.0 3.0 8.0 979 KB

Kanban Terminal App written in Python

License: MIT License

Python 100.00%

cli-app kanban kanban-board-application terminal-based kanban-python python

kanban-python's Introduction

kanban-python

A Terminal Kanban Application written in Python to boost your productivity 🚀

Introduction

Welcome to kanban-python, your Terminal Kanban-Board Manager.

The clikan Kanban App inspired me to write my own Terminal Kanban Application since I preferred a more simple and guided workflow.

kanban-python also comes with more features, like custom column creation, automatic scanning and customizable config file to support you being productive.

This package was developed with pyscaffold, which provides awesome project templates and takes over much of the boilerplate for python packaging. It was a great help for developing my first package and I can highly recommend it.

Features

Colorful and Interactive

kanban-python uses rich under the hood to process user input and display nice looking kanban-boards to the terminal.
Each task has a unique ID per board and also has an optional Tag and Due Date associated with it, which are displayed alongside its Title

Following the XDG basedir convention

kanban-python utilizes platformdirs user_config_dir to save the config file and user_data_dir for the board specific task files. After creating your first board, you can use kanban configure to show the current settings table. The config path in the table caption and the path for the task files can be found in the kanban_boards section.

Scanning of Files for automatic Task Creation

kanban-python can scan files of defined types for specific patterns at start of line. Check Automatic Task Creation for more Infos.

Customizable Configfile

A pykanban.ini file gets created on first initialization in a kanban-python folder in your user_config_dir-Directory. This can be edited manually or within the kanban-python application. It tracks the location for all your created boards.
- Active_Board: current board that is shown when using kanban-command
- Done_Limit: If the amount of tasks exceed this number in the Done column, the first task of that column gets its status updated to Archived and is moved into that column. (default: 10)
- Column_Min_Width: Sets the minimum width of columns. (default: 40)
- Show_Footer: Shows the table footer with package name and version. (default: True)
- Files: Space seperated filetypes to search for patterns to create tasks. (default: .py .md)
- Patterns: Comma seperated patterns to search for start of line to create tasks.
  (default: # TODO,#TODO,# BUG)

Task Storage File for each Board

Each created board comes with its own name and pykanban.json file, which stores all tasks for that board. The files are stored in board specific folders under $USER_DATA_DIR/kanban-python/kanban_boards/<BOARDNAME>. When changing Boards you also get an overview over tasks in visible columns for each board and the most urgent or overdue task on that board.

Customizable Columns

kanban-python comes with 5 pre-defined colored columns: [Ready, Doing, Done, Archived, Deleted] More column can be added manually in the pykanban.ini, the visibility can be configured in the settings with kanban configure.

Time Tracking of Task duration in Doing

For each task it is tracked, how long it was in the Doing column, based on the moments when you update the task status. The initial Task structure on creation looks as follows:

Report Creation for completed Tasks

When you use kanban report a github-like contribution map is displayed for the current year, Also a markdown file is created with all tasks comleted based on the moment, when the tasks were moved to Done Column.

Installation

You can install kanban-python with:

python -m pip install kanban-python

or using pipx:

pipx install kanban-python

Usage

After Installation of kanban-python, there are 5 commands available:

Create new Boards

kanban init

Is used to create a new kanban board i.e. it asks for a name and then creates a pykanban.json file with a Welcome Task. On first use of any command, the pykanban.ini configfile and the kanban-python folder will be created automatically.

Interact with Tasks/Boards

kanban

This is your main command to interact with your boards and tasks. It also gives the option to show the current settings and adjust them. Adjusting the settings can also be done directly by using the command kanban configure:

Use Ctrl-C or Ctrl-D to exit the application at any time. ⚠️ If you exit in the middle of creating/updating a task, or changing settings, your progress wont be saved.

Automatic Task Creation

kanban scan

After executing this command, kanban-python scans your current Directory recursively for the defined filetypes and searches for lines that start with the pattern provided.

After confirmation to add the found tasks to table they will be added to the board. The alphanumeric Part of the Pattern will be used as tag. The filepath were the task was found will be added as description of the task.

Create Report

kanban report

Goes over all your Boards and creates a single markdown file by checking the Completion Dates of your tasks. Also shows a nice github-like contribution table for the current year.

Change Settings

kanban configure

To create a new custom Columns, you have to edit the pykanban.ini manually and add a new column name + visibility status under the settings.columns.visible section. The other options are all customizable now via the new settings menu.

Feedback and Issues

Feel free to reach out and share your feedback, or open an Issue, if something doesnt work as expected. Also check the Changelog for new updates.

⚠️ With release v0.3.0 kanban-python switched to the XDG Basedir Spec. So some file migrations and config edits might be needed to continue working with your already created boards if you update from v0.2.X to v0.3.X

Note

This project has been set up using PyScaffold 4.5. For details and usage information on PyScaffold see https://pyscaffold.org/.

kanban-python's People

Contributors

Stargazers

Watchers

Forkers

zwm5000 lolszz faiqashabbir bgarrofe hosseinim018 nvgbr evaristoneto daria-codes

kanban-python's Issues

Please don't spam home directory

» kanban init
Created new pykanban.ini file @Home Directory
Use 'kanban init' to create kanban boards
» # WTF?
» cat ~/pykanban.ini
[settings.general]
Active_Board = 
Column_Min_Width = 35
Done_Limit = 10
Show_Footer = True

[settings.columns.visible]
Ready = True
Doing = True
Done = True
Deleted = False
Archived = False

[kanban_boards]

To place a configuration file as a visible file in the root of the user's home directory, is a no go.

Preferrably, use the directory $XDG_CONFIG_HOME/kanban-python, where $XDG_CONFIG_HOME defaults to ~/.config.

If you do not like the XDG specification, at least put the config file in an invisible dot directory — e.g., ~/.kanban-python.

To place a configuration file as a visible file in the root of the user's home directory, is a no go.

Dependency conflicts in pipx

Trying to install using pipx returns the following dependency conflict:

PIP STDOUT
----------
Collecting kanban-python
  Downloading kanban_python-0.3.10-py3-none-any.whl (22 kB)
  Downloading kanban_python-0.3.9-py3-none-any.whl (22 kB)
  Downloading kanban_python-0.3.8-py3-none-any.whl (22 kB)
  Downloading kanban_python-0.3.7-py3-none-any.whl (21 kB)
  Downloading kanban_python-0.3.6-py3-none-any.whl (19 kB)
  Downloading kanban_python-0.3.5-py3-none-any.whl (19 kB)
  Downloading kanban_python-0.3.4-py3-none-any.whl (19 kB)
  Downloading kanban_python-0.3.3-py3-none-any.whl (19 kB)
  Downloading kanban_python-0.3.2-py3-none-any.whl (18 kB)
Collecting platformdirs<4
  Downloading platformdirs-2.4.0-py3-none-any.whl (14 kB)
Collecting kanban-python
  Downloading kanban_python-0.3.1-py3-none-any.whl (18 kB)
  Downloading kanban_python-0.3.0-py3-none-any.whl (18 kB)
  Downloading kanban_python-0.2.2-py3-none-any.whl (17 kB)
  Downloading kanban_python-0.2.1-py3-none-any.whl (17 kB)
  Downloading kanban_python-0.2.0-py3-none-any.whl (15 kB)
  Downloading kanban_python-0.1.4-py3-none-any.whl (14 kB)
  Downloading kanban_python-0.1.3-py3-none-any.whl (14 kB)
  Downloading kanban_python-0.1.1-py3-none-any.whl (14 kB)
  Downloading kanban_python-0.1.0-py3-none-any.whl (14 kB)
  Downloading kanban_python-0.0.5-py3-none-any.whl (14 kB)

The conflict is caused by:
    kanban-python 0.3.10 depends on platformdirs<4 and >=3
    kanban-python 0.3.9 depends on platformdirs<4 and >=3
    kanban-python 0.3.8 depends on platformdirs<4 and >=3
    kanban-python 0.3.7 depends on platformdirs<4 and >=3
    kanban-python 0.3.6 depends on platformdirs<4 and >=3
    kanban-python 0.3.5 depends on platformdirs<4 and >=3
    kanban-python 0.3.4 depends on platformdirs<4 and >=3
    kanban-python 0.3.3 depends on platformdirs<4 and >=3
    kanban-python 0.3.2 depends on rich>=13.7.0
    kanban-python 0.3.1 depends on rich>=13.7.0
    kanban-python 0.3.0 depends on rich>=13.7.0
    kanban-python 0.2.2 depends on rich>=13.7.0
    kanban-python 0.2.1 depends on rich>=13.7.0
    kanban-python 0.2.0 depends on rich>=13.7.0
    kanban-python 0.1.4 depends on rich>=13.7.0
    kanban-python 0.1.3 depends on rich>=13.7.0
    kanban-python 0.1.1 depends on rich>=13.7.0
    kanban-python 0.1.0 depends on rich>=13.7.0
    kanban-python 0.0.5 depends on rich>=13.7.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict


PIP STDERR
----------
ERROR: Cannot install kanban-python==0.0.5, kanban-python==0.1.0, kanban-python==0.1.1, kanban-python==0.1.3, kanban-python==0.1.4, kanban-python==0.2.0, kanban-python==0.2.1, kanban-python==0.2.2, kanban-python==0.3.0, kanban-python==0.3.1, kanban-python==0.3.10, kanban-python==0.3.2, kanban-python==0.3.3, kanban-python==0.3.4, kanban-python==0.3.5, kanban-python==0.3.6, kanban-python==0.3.7, kanban-python==0.3.8 and kanban-python==0.3.9 because these package versions have conflicting dependencies.
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies

Feature request: interpret ^D as quit

It seems kanban expects ^C for quitting.

Usually on Linux, ^D (EOF) is regarded as a signal to stop reading from standard input. When giving kanban a ^D at the “Choose wisely” prompt, kanban dies with an EOFError.

I suggest treating ^C and ^D as synonyms.

(And perhaps allow q for quitting, too.)

How to set terminal on MAC so left/right arrows work.

On a MAC if I'm typing in a line of text and make a typo mistake, when I press the left-arrow to go back to the middle of the string I'm typing, it gives me the character sequence "^[[D" So it isn't interpreting the left arrow key correctly.

Changing the board specific .json files to be saved in a central location

Thinking about storing them directly in the .kanban-python folder next to the configfile.

Options:

as plain files boardname.json
in an additional folder as kanban_boards/boardname.json
each in its own folder under boardname/pykanban.json
mix of 2. and 3. in a folder kanban boards under kanban_boards/boardname/pykanban.json

This would prevent spreading of multiple pykanban.json files across many directories.

Feature request: automaticly add #todo

This looks great!

I use various vscode plugins that are able to record a todo list based on lines tagged with #todo in any file in your project. Would it be able to do any variant of this, maybe a variant of it - say adding a file if todo item automatically to the canban board (if using a different app to compile the todo list).

Feature request: Improvement for user configuration

Consider using tools like platformdirs to save the config file (and many other files) in standard directories with multi-platform support. It is very important to follow XDG when placing files inside other people's systems, that way the information is well organized in the OS. You can see a simple example in this project of mine where I also create config files using configparse (and also log files) with the help of platformdirs to automatically retrieve the correct path that should store those files.

It is really easy to implement and the benefit is huge for the open-source community!

Unable to instantiate the Kanban

Hi,

This is the first time I installed "kanban-python". After installing the package, I ran the following command but got the below error:

kanban init

Traceback (most recent call last):
  File "/opt/homebrew/Caskroom/miniforge/base/bin/kanban", line 5, in <module>
    from kanban_python.app import run
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.9/site-packages/kanban_python/app.py", line 25, in <module>
    from kanban_python import cli_parser, config, controls, utils
  File "/opt/homebrew/Caskroom/miniforge/base/lib/python3.9/site-packages/kanban_python/controls.py", line 106, in <module>
    def add_tasks_to_db(tasks: dict | list[dict]) -> None:
TypeError: unsupported operand type(s) for |: 'type' and 'types.GenericAlias'

What could be the reason for this?

Feature: Add Due Dates To Tasks and display days left on board

Add "Due_Date" to task.
Display Days remaining on board
Display Days remaining onChange Board Action View
~~- [ ] Add Option to show due date to config?~~ (takes only little space like |02| behind task name)
adjust Board caption for task structure
Update Readme + new Screenshots

Improve config settings via cli input without manual editing

Thoughts:

potential more sophisticated menu with different actions for the config sections
Goal: minimize manual editing of config file
limit config setting to kanban configure command

Feature: Create Reports based on Tasks completion

Monthly Report over all Boards like:

# December
## 06.12.2023
- (TAG) Task Title 1 [maybe add duration or board information?]
- (TAG) Task Title 2
## 07.12.2023
- (TAG) Task Title 3

can be used with kanban report. Created in user_data_dir/reports/year as month_year.md, full path e.g. user_data_dir/reports/2023/december_2023.md

Feature Request - Add `show task` info option

It would be great to add an option to dump task info in a pretty way, i.e. adding show task to Whats up!?, how can I help you being productive today 🚀 default question.

Currently, to get a task description you need to run [2] 🔃 Update/Check Task and step through the 4 questions including one which cannot be passed as empty (assign the task stage).

Maybe something like:

# add to the prompt
[0] show task
# user inputs ID
Enter ID: 01
# outputs 
ID: 01
Title: Some Task
Tag: BUG
Task Description: Some longer text

Another nice option building off this would be able to show all tasks with a certain tag:

# add to the prompt
[0] show task/s
# user inputs ID
Enter ID or Tag: BUG

# outputs 
ID: 01
Title: Some Task
Tag: BUG
Task Description: Some longer text

ID: 04
Title: new Task
Tag: BUG
Task Description: Some longer text

ID: 05
Title: new new Task
Tag: BUG
Task Description: Some longer text

Feature: Show more board info for each board e.g. amount of Tasks, when changing boards

Or another solution, to give a better overview over all boards.

e.g. big board view table with sections for each table (similar to sections in settings table)

Either way it requires reading all json files of all boards on board change.