kboard 0.1.0__tar.gz

kboard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Óscar Miranda
+
+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.

kboard-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: kboard
+Version: 0.1.0
+Summary: Console-based Kanban task manager created in Python.
+License: MIT License
+         
+         Copyright (c) 2026 Óscar Miranda
+         
+         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.
+License-File: LICENSE
+Keywords: kanban,board,project,management,cli
+Author: Óscar Miranda
+Author-email: oscarmiranda3615@gmail.com
+Requires-Python: >=3.14.2
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Dist: rich (>=14.3.2,<15.0.0)
+Requires-Dist: sqlalchemy (>=2.0.46,<3.0.0)
+Requires-Dist: typer (>=0.21.1,<0.22.0)
+Project-URL: Homepage, https://github.com/OscarM3615/kboard/
+Project-URL: Repository, https://github.com/OscarM3615/kboard/
+Description-Content-Type: text/markdown
+
+# kboard
+
+Console-based Kanban task manager created in Python.
+
+Create and manage tasks visually in your terminal using handy commands.
+
+## Features
+
+- CLI based Kanban board.
+- Easy setup.
+- Simple commands.
+- Structured database file.
+
+## Installation
+
+Install using pip running the following command in the terminal:
+
+## Usage
+
+If you installed the library, you can use the CLI as a system command:
+
+```sh
+kb COMMAND [ARGS] ...
+```
+
+### Examples
+
+Here are some examples of the commands available:
+
+```sh
+# List the existing boards.
+kb board ls
+
+# Create a new board.
+kb board add "Board name"
+
+# Add a task to the backlog.
+kb task add "Task title"
+
+# Add a task to a board with high priority.
+kb task add --board 1 --priority 3 "Important task"
+
+# Move a task
+kb task mv 2
+```
+
+## Contributing
+
+Thank you for considering contributing to my project! Any pull requests are
+welcome and greatly appreciated. If you encounter any issues while using
+the project, please feel free to post them on the issue tracker.
+
+To contribute to the project, please follow these steps:
+
+1. Fork the repository.
+2. Add a new feature or bug fix.
+3. Commit them using descriptive messages, using
+   [conventional commits](https://www.conventionalcommits.org/) is recommended.
+4. Submit a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
+for more details.
+

kboard-0.1.0/README.md

@@ -0,0 +1,64 @@
+# kboard
+
+Console-based Kanban task manager created in Python.
+
+Create and manage tasks visually in your terminal using handy commands.
+
+## Features
+
+- CLI based Kanban board.
+- Easy setup.
+- Simple commands.
+- Structured database file.
+
+## Installation
+
+Install using pip running the following command in the terminal:
+
+## Usage
+
+If you installed the library, you can use the CLI as a system command:
+
+```sh
+kb COMMAND [ARGS] ...
+```
+
+### Examples
+
+Here are some examples of the commands available:
+
+```sh
+# List the existing boards.
+kb board ls
+
+# Create a new board.
+kb board add "Board name"
+
+# Add a task to the backlog.
+kb task add "Task title"
+
+# Add a task to a board with high priority.
+kb task add --board 1 --priority 3 "Important task"
+
+# Move a task
+kb task mv 2
+```
+
+## Contributing
+
+Thank you for considering contributing to my project! Any pull requests are
+welcome and greatly appreciated. If you encounter any issues while using
+the project, please feel free to post them on the issue tracker.
+
+To contribute to the project, please follow these steps:
+
+1. Fork the repository.
+2. Add a new feature or bug fix.
+3. Commit them using descriptive messages, using
+   [conventional commits](https://www.conventionalcommits.org/) is recommended.
+4. Submit a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
+for more details.

kboard-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "kboard"
+version = "0.1.0"
+description = "Console-based Kanban task manager created in Python."
+authors = [
+    {name = "Óscar Miranda", email = "oscarmiranda3615@gmail.com"}
+]
+license = {file = "LICENSE"}
+readme = "README.md"
+keywords = ["kanban", "board", "project", "management", "cli"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.14.2"
+dependencies = [
+    "typer (>=0.21.1,<0.22.0)",
+    "rich (>=14.3.2,<15.0.0)",
+    "sqlalchemy (>=2.0.46,<3.0.0)"
+]
+
+[project.urls]
+homepage = "https://github.com/OscarM3615/kboard/"
+repository = "https://github.com/OscarM3615/kboard/"
+
+[project.scripts]
+kb = 'kboard.app:app'
+
+[tool.poetry]
+packages = [{include = "kboard", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

kboard-0.1.0/src/kboard/app.py

@@ -0,0 +1,16 @@
+import typer
+
+from .commands import backlog, board, configure, task
+
+
+app = typer.Typer(no_args_is_help=True,
+                  context_settings={'help_option_names': ['-h', '--help']})
+
+app.add_typer(configure.app)
+app.add_typer(backlog.app)
+app.add_typer(board.app)
+app.add_typer(task.app)
+
+
+if __name__ == '__main__':
+    app()

kboard-0.1.0/src/kboard/commands/backlog.py

@@ -0,0 +1,25 @@
+from rich import print
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+import typer
+
+from ..config import engine
+from ..models import Board, Task
+
+
+app = typer.Typer()
+
+
+@app.command()
+def backlog():
+    """Display tasks from backlog.
+
+    The backlog is composed of tasks with no assigned board.
+    """
+    with Session(engine) as session:
+        tasks = session.execute(
+            select(Task).where(Task.board_id == None)).scalars().all()
+
+        board = Board(name='Backlog', tasks=tasks)
+
+        print(board)

kboard-0.1.0/src/kboard/commands/board.py

@@ -0,0 +1,118 @@
+from typing import Annotated
+
+import typer
+from rich import print
+from rich.console import Group
+from rich.panel import Panel
+from sqlalchemy import delete, select
+from sqlalchemy.orm import Session
+
+from ..config import engine
+from ..models import Board, Status, Task
+from ..utils import success, error
+
+
+app = typer.Typer(name='board', help='Manage boards.', no_args_is_help=True)
+
+
+@app.command()
+def ls():
+    """List existing boards.
+    """
+    with Session(engine) as session:
+        boards = session.execute(select(Board)).scalars().all()
+
+        titles = [b.inline() for b in boards]
+
+        print(Panel(Group(*titles), title='Boards', title_align='left',
+                    border_style='blue'))
+
+
+@app.command()
+def add(name: Annotated[str, typer.Argument(help='Board name.')]):
+    """Create a new board.
+    """
+    board = Board(name=name)
+
+    with Session(engine) as session:
+        session.add(board)
+        session.commit()
+
+        success(f'Created board "{board.name}" ({board.id}).')
+
+
+@app.command(help='Rename a board.')
+def rename(id: Annotated[int, typer.Argument(help='Board ID.')],
+           name: Annotated[str, typer.Argument(help='New name.')]):
+    """Rename a board.
+    """
+    with Session(engine) as session:
+        board = session.get(Board, id)
+
+        if not board:
+            return error('Board not found.')
+
+        board.name = name
+        session.commit()
+
+        success(f'Renamed board to "{board.name}".')
+
+
+@app.command()
+def rm(id: Annotated[int, typer.Argument(help='Board ID.')],
+       force: Annotated[bool, typer.Option(
+           '--force', '-f',
+           prompt='Are you sure you want to delete the board?',
+           help='Force deletion without confirmation.')] = False):
+    """Delete existing board.
+
+    If --force is not used, will ask for confirmation.
+    """
+    if force:
+        with Session(engine) as session:
+            board = session.get(Board, id)
+
+            if not board:
+                return error('Board not found.')
+
+            session.delete(board)
+            session.commit()
+
+            success(f'Deleted board "{board.name}".')
+
+
+@app.command()
+def show(id: Annotated[int, typer.Argument(help='Board ID.')]):
+    """Display board and its tasks.
+    """
+    with Session(engine) as session:
+        board = session.get(Board, id)
+
+        if not board:
+            return error('Board not found.')
+
+        print(board)
+
+
+@app.command()
+def clean(id: Annotated[int, typer.Argument(help='Board ID.')],
+          force: Annotated[bool, typer.Option(
+              '--force', '-f',
+              prompt='Are you sure you want to delete completed tasks?',
+              help='Force deletion without confirmation.', )] = False):
+    """Delete completed tasks from a board.
+
+    If --force is not used, will ask for confirmation.
+    """
+    if force:
+        with Session(engine) as session:
+            board = session.get(Board, id)
+
+            if not board:
+                return error('Board not found.')
+
+            session.execute(delete(Task).where(Task.board_id == board.id,
+                                               Task.status == Status.COMPLETED))
+            session.commit()
+
+            success('Deleted completed tasks.')

kboard-0.1.0/src/kboard/commands/configure.py

@@ -0,0 +1,17 @@
+import typer
+
+from ..config import engine
+from ..models import Base
+from ..utils import success
+
+
+app = typer.Typer()
+
+
+@app.command()
+def configure():
+    """Create and initialise data file.
+    """
+    Base.metadata.create_all(engine)
+
+    success('Data file created successfully.')

kboard-0.1.0/src/kboard/commands/task.py

@@ -0,0 +1,130 @@
+from typing import Annotated
+
+import typer
+from sqlalchemy.orm import Session
+
+from ..config import STATUS_NAMES, engine
+from ..models import Board, Priority, Status, Task
+from ..utils import error, success
+
+
+app = typer.Typer(name='task', help='Manage tasks.', no_args_is_help=True)
+
+
+@app.command()
+def add(title: Annotated[str, typer.Argument(help='Task title.')],
+        priority: Annotated[Priority, typer.Option(
+            '--priority', '-p', help='Task priority.')] = Priority.NORMAL,
+        tag: Annotated[str | None, typer.Option(
+            '--tag', '-t', help='Task custom tag.',
+        )] = None,
+        board_id: Annotated[int | None, typer.Option(
+            '--board', '-b', help='Board ID to assign to the task.')] = None):
+    """Add a new task.
+
+    The task can be preassigned to a board using the --board option.
+    """
+    with Session(engine) as session:
+        if board_id:
+            board = session.get(Board, board_id)
+
+            if not board:
+                return error('Board not found.')
+        else:
+            board = None
+
+        task = Task(title=title, priority=priority, tag=tag, board=board)
+
+        session.add(task)
+        session.commit()
+
+        success(f'Created task with ID {task.id}.')
+
+
+@app.command()
+def edit(id: Annotated[int, typer.Argument(help='Task ID.')],
+         title: Annotated[str | None, typer.Option(
+             '--title', help='New task title.')] = None,
+         priority: Annotated[Priority | None, typer.Option(
+             '--priority', '-p', help='New task priority.')] = None,
+         tag: Annotated[str | None, typer.Option(
+             '--tag', '-t', help='Task custom tag.',
+         )] = None,
+         board_id: Annotated[int | None, typer.Option(
+        '-b', '--board', help='New board ID (use -1 to unasign).')] = None):
+    """Edit existing task attributes.
+
+    All parameters and options from the `add` command are optional here.
+    """
+    with Session(engine) as session:
+        task = session.get(Task, id)
+
+        if not task:
+            return error('Task not found.')
+
+        new_attrs = {'title': title, 'priority': priority, 'tag': tag}
+        task.update(**new_attrs)
+
+        if board_id is not None:
+            if board_id != -1:
+                board = session.get(Board, board_id)
+
+                if not board:
+                    return error('Board not found.')
+            else:
+                board = None
+            task.board = board
+
+        session.commit()
+
+        success(f'Updated task "{task.title}" attributes.')
+
+
+@app.command()
+def mv(id: Annotated[int, typer.Argument(help='Task ID.')],
+       steps: Annotated[int, typer.Option(
+           '--steps', '-s', help='Number of steps to move.')] = 1):
+    """Move a task from its current status.
+
+    To customise the direction or number of steps, use the --steps option.
+
+    To move a task backwards the steps must be negative.
+    """
+    with Session(engine) as session:
+        task = session.get(Task, id)
+
+        if not task:
+            return error('Task not found.')
+
+        try:
+            task.status = Status(task.status + steps)
+        except ValueError:
+            return error(f'Unable to move {steps} step(s).')
+
+        session.commit()
+
+        success(
+            f'Moved task "{task.title}" to [cyan]{STATUS_NAMES[task.status]}[/].')
+
+
+@app.command()
+def rm(id: Annotated[int, typer.Argument(help='Task ID.')],
+       force: Annotated[bool, typer.Option(
+           '--force', '-f',
+           prompt='Are you sure you want to delete the task?',
+           help='Force deletion without confirmation.')] = False):
+    """Delete existing task.
+
+    If --force is not used, will ask for confirmation.
+    """
+    if force:
+        with Session(engine) as session:
+            task = session.get(Task, id)
+
+            if not task:
+                return error('Task not found.')
+
+            session.delete(task)
+            session.commit()
+
+            success(f'Deleted task with ID {task.id}.')

kboard-0.1.0/src/kboard/config.py

@@ -0,0 +1,25 @@
+import os
+from pathlib import Path
+
+from sqlalchemy import create_engine
+
+from .enums import Priority, Status
+
+
+DB_PATH = Path(os.environ.get('KBOARD_HOME', Path.home())) / 'kboard.db'
+
+STATUS_NAMES: dict[Status, str] = {
+    Status.TO_DO: 'To do',
+    Status.IN_PROGRESS: 'In progress',
+    Status.REVIEW: 'Review',
+    Status.COMPLETED: 'Completed',
+}
+
+STATUS_COLOURS: dict[Status, str] = {
+    Status.TO_DO: 'white',
+    Status.IN_PROGRESS: 'blue',
+    Status.REVIEW: 'magenta',
+    Status.COMPLETED: 'green',
+}
+
+engine = create_engine(f'sqlite:///{DB_PATH}')

kboard-0.1.0/src/kboard/enums.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class Priority(int, Enum):
+    LOW = 1
+    NORMAL = 2
+    HIGH = 3
+
+
+class Status(int, Enum):
+    TO_DO = 1
+    IN_PROGRESS = 2
+    REVIEW = 3
+    COMPLETED = 4

kboard-0.1.0/src/kboard/models.py

@@ -0,0 +1,107 @@
+from collections import defaultdict
+from typing import overload
+from rich import box
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+from .config import STATUS_COLOURS, STATUS_NAMES
+from .enums import Priority, Status
+
+
+class Base(DeclarativeBase):
+    ...
+
+
+class Board(Base):
+    __tablename__ = 'boards'
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+    tasks: Mapped[list['Task']] = relationship(back_populates='board',
+                                               cascade='all, delete',
+                                               passive_deletes=True)
+
+    def __rich__(self) -> RenderableType:
+        """Display board as a Kanban table.
+
+        :return: rich renderable object
+        """
+        statuses = defaultdict(list)
+
+        for task in self.tasks:
+            statuses[task.status].append(task)
+
+        table = Table(title=self.name, box=box.DOUBLE, expand=True)
+
+        for s in Status:
+            table.add_column(
+                f'[{STATUS_COLOURS[s]}]{STATUS_NAMES[s]}[/] ({len(statuses[s])})',
+                ratio=1
+            )
+
+        table.add_row(*[Group(*statuses[s]) for s in Status])
+
+        return table
+
+    def inline(self) -> RenderableType:
+        return f'\\[[cyan]{self.id}[/]] {self.name}'
+
+
+class Task(Base):
+    __tablename__ = 'tasks'
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str]
+    priority: Mapped[Priority]
+    tag: Mapped[str] = mapped_column(default='')
+    status: Mapped[Status] = mapped_column(default=Status.TO_DO)
+    board_id: Mapped[int | None] = mapped_column(
+        ForeignKey('boards.id', ondelete='CASCADE'))
+
+    board: Mapped[Board | None] = relationship(back_populates='tasks')
+
+    def __rich__(self) -> RenderableType:
+        """Display task as a Kanban card.
+
+        :return: rich renderable object
+        """
+        content = self.title
+
+        if self.priority == Priority.LOW:
+            content = f'[bright_black]{content}[/]'
+        elif self.priority == Priority.HIGH:
+            content = f'[yellow]\\[!][/] {content}'
+
+        if self.tag:
+            content += f' ([cyan]{self.tag}[/])'
+
+        return Panel(content, title=str(self.id), title_align='left',
+                     border_style=STATUS_COLOURS[self.status])
+
+    @overload
+    def update(self, *, title: str | None = None,
+               priority: Priority | None = None, tag: str | None = None,
+               status: Status | None = None) -> None:
+        """Update multiple instance attributes in a single call.
+
+        To skip a field leave is as ``None``.
+
+        :param title: new title
+        :param priority: new priority
+        :param tag: new tag
+        :param status: new status
+        """
+        ...
+
+    @overload
+    def update(self, **kwargs) -> None:
+        ...
+
+    def update(self, **kwargs) -> None:
+        for attr, value in kwargs.items():
+            if value is not None:
+                setattr(self, attr, value)

kboard-0.1.0/src/kboard/utils.py

@@ -0,0 +1,19 @@
+from rich import print
+from rich.panel import Panel
+
+
+def success(message: str) -> None:
+    """Display a success message.
+
+    :param message: message to display
+    """
+    print(Panel(message, title='Success', title_align='left',
+                border_style='green'))
+
+
+def error(message: str) -> None:
+    """Display an error message.
+
+    :param message: Message to display.
+    """
+    print(Panel(message, title='Error', title_align='left', border_style='red'))