Problem

It feels like there isn't clear differentiation of use between CliResult/CliError and generic anyhow::Errors. At time I'll myself forcing myself to create one or the other depending on how deeper logic handles errors.

Solution

TBD

Problem

Fresh projects are raw and thus can easily get out of hand very early. One of the goals for huak is to encourage scalable collaboration. That includes tightening standards for everything from contributions to vision.

Solution

Starting with what can be standardized in a GitHub repository:

• Labels
• Label automation
• Coverage reporting
• Starter Issue and PR templates
• Approval requirements
• Other GitHub Actions

Issues

• #49
• #66

huak lint

Run huak lint to run linting for Python code.

The first version of this command would:

• Execute flake8 from .venv.
• Use pep-compliant flake8 configuration like --ignore E203,W503.
• Execute mypy from .venv.

huak init

Run huak init to initialize the current directory with a pyroject.toml.

The first version of this command would:

• Check if a pyproject.toml already exists (and if so exits).
• If no pyproject.toml exists prompt the user for manual setup.
• Updates the author configuration step, allowing users to add an author at a time.
• Allow users to add main and dev dependencies to the pyproject.toml.

Problem

Would like to get a more directional structure for the project in place to remove design ambiguity for Huak.

Solution

Referencing #1 for design objectives.

Huak's components

Domain-driven design is cool. I wouldn't say this is DDD, but it's definitely inspired by it.

CLI

The CLI application is the huak binary. As such its application implementation lives in the bin space of the project. Here only the application-level code lives. It's a light layer of code to implement the program users interact with and execute commands from. It defines the CLI application with command parsing and control, command definitions and run functions, and various general and subcommand arguments.

Configuration

Configuration of Huak and (transitively) configuration of Python projects/packages is implemented here. This includes pyproject.toml data serialization and de-serialization, dependency/requirements standardization, etc..

Environment

Many parts of Huak already attempt to utilize environment artifacts such as virtual environments and directories (often current working dir). Over time the way an environment is understood, utilized, and tracked by Huak will evolve, so standardizing this behind an early Environment structure to implement the high level interface for the application is enough for now.

Packaging

Early versions of Huak may not truly implement packaging facilities, but I'd like to indicate this abstraction with the namespace. In this space I'll likely differentiate between environment, configuration, and packaging-specific logic. An example would be logic to build and publish the package.

Project

Projects are composed of configuration, environments, and packaging facilities. Early versions of Huak may not implement much logic in the project space, but I'll create it to indicate that direction.

Operations

This is module space for implementations depending on contexts (like Projects, Environments, etc.) and additional parameters and/or functions. The CLI application would be mainly integrated with this part of Huak's library.

Integration

Edit: I really don't want a broad "integration" space like this. Maybe individual integrations can be given their own spaces at this level of the project without it getting too busy. It may make more sense to push them into one space like this if it becomes necessary. TBD.

Over time more and more projects will be integrated with the Huak application. I'm not entirely sure how to organize this today, but I'd like to indicate those plans by starting an integration module space. The first version of Huak will, at the very least, need to implement features that integrate with PyPI. So I'll start with an API there for it.

First pass could lean on docs-rs. Not opposed to playing with other tools/hosts.

https://github.com/charliermarsh/ruff

• astral-sh/ruff#170

Instead of using zip files let's check in the contents. Either as regular files without ignoring the typically ignored contents or as rust implementations.

I'd really like for this to be in a GitHub org, but there hasn't really been too much progress interesting any potential core contributors. Having been the sole member of huak-rs, it feels a bit strange to be using a GitHub org for the project at this time. Almost wasteful.

I'll keep using visibility boosters like milestones and an issue board for now, but I think I'll transfer this to my personal account until Huak can take advantage of GitHub's team features.

Another change I'm going to make is to remove the use of Discord. I want to minimize distractions and just focus on building a great Huak. I found myself checking discord to make sure I wasn't ignoring any new questions, but it wasn't being used. The less context switching the better (at least this early on).

I'm leaving this GitHub issue open to invite comments on the subject.

Depends on #50

The first iteration of version will just look for pyproject.toml in the current directory.

Feature Request

Name: CONTRIBUTING.md

About: Create a guide for contributors to get started.

Make sure to include a link to the discord.

1. Create or grab an issue
2. Fork and create your branch
3. Setup pre-commit to ensure your PR passes tests
4. Submit your PR

Style guide to keep code consistent between all developers.

huak audit

Run huak audit to scan for packages in your project's virtual environment with known vulnerabilities.

huak fmt

Run huak fmt to format python code.

The first version of fmt would:

• Execute black using .venv-installed black.
• Use pep-adhering black configuration like --line-length 79.
• Execute isort using .venv-installed isort.
• Use black-compatible isort configuration like:

[tool.isort]
multi_line_output = 3
line_length = 79
include_trailing_comma = true

• Add --check flag.

Feature Request

Name: Documentation for what is the purpose of this project?

About: Documentation is really important for a project, it's a starting point for both users and contributors. how about creating docs for installation, contribution, getting started, features, and more?

https://github.com/rust-lang/highfive

$ huak new

Enter a name: my-project
Would you like to manually configure 'my-project' (y,N)? y
Setting up 'pyproject.toml'...
Please enter a version (0.0.1):
Set 'my-project-0.0.1'.
Please enter a description (""):
'my-project' ("").
Please enter authors ([""]):
'my-project' authored by [""].
Would you like to add main dependencies (Y,n)?
Please enter a dependency: click
Searching PyPi...
The following packages were found:
- [0] click
- [1] ...
Please select the package you'd like to add (0):
Adding [0] click...
Please enter another dependency (y,N):
Would you like to add dev dependencies (y,N):
Adding huak-required dev dependencies...
Generating project...
Setup complete! 

TODO:

• #38

Feature Request

About: Currently it looks like we're erroring if dist cannot be found. I think we can just silently fail.

This is the tracking issue for implementations of opinionated project bootstrapping.

Some ideas:

• Always depend on black, flake8, mypy, pytest for standard commands lint, fmt, test, etc..
• If .git is found, setup pre-commit.

huak test

Run huak test to test Python code.

The first version of test would:

• Execute pytest from .venv.

We should add a branching system, and an explanation of that branching system in our CONTRIBUTING.md, if you are not sure what is a branching system, go through this rust-pip: CONTRIBUTING.md

Hope this issue is helpful (:

Scope for the Initial Alpha Release

For the first iteration of the project scope will remain pretty tight. As more ground is covered more scope can be added (see below for the Future Releases section). While some necessary features may not be implemented in this first iteration, the long-term goal of this project is to build a performant cargo-like package manager for the Python ecosystem.

The first release (Initial Alpha Release) will implement many of the features listed here by simply wrapping existing projects. Future releases will chip away at eliminating any wrapped execution.

Initial Alpha Release

• Learn Rust - A big motivator for starting this project is to learn Rust.
• No dependency resolution - We're wrapping pip for installation and not introducing any dependency resolution as part of Huak’s initial release.
• No optional dependencies
• No plugins
• Basic distribution via GitHub release artifacts
• Minimal project setup features (i.e. huak new, huak init, huak add, etc.) - The goal is to dogfood the initial release in parallel to learning to write high quality Rust code.
• Install pyproject.toml dependancies using huak install

Commands

• version: Display the project's version
• new: Create Python project from scratch
• init: Initialize an existing Python project containing a pyproject.toml
• help: Display descriptive help message about using huak
• update: Update dependencies declared in pyproject.toml
• activate: Activate the project's virtual environment
• run: Run commands within the project's virtual environment context
• build: Build the current project
• clean: Cleans package tarball and wheels if they exist (may also clean any cache used by Huak)
• remove: Removes a dependency from the current project's virtual environment and pyproject.toml
• fmt: Format Python code
• lint: Lint and check types of Python code
• install: Install dependencies to a virtual environment
• add: Add dependencies to a virtual environment

Future Releases

• Dependency resolution
• Optional dependencies
• Plugins (from Rust or Python)
• Huak library available from PyPi (great for package metadata and other utilities)
• Broad distribution and availability
• Additional configuration format compatibility (requirements.txt, etc.)
• Pure Rust implementations
• Additional QoL features

See the Issue Board's backlog for more planned features.

Since one of the main goals for Huak is for it to become a performant package manager for the Python ecosystem via Rust, there are a few problems this project aims to be a part of efforts for their solutions:

1. Python tooling rewrites (linters, formatters, etc.)
2. Inspiring and assisting Python community contributions to Rust projects
3. Configuration capabilities via language interop

Feature Request

Name: Improve templates like ISSSUE_TEMPLATEs and PULL_REQUEST_TEMPLATEs

About:

Here's some of the feedback I have so far. We can use this as a kind of tracking issue too.

• Feature Request template asks for title and name. It feels slightly redundant. Maybe we remove the name requirement.
• The markdown adds large "Feature Request" text to the issue. I think we maybe make that smaller. It feels like it takes over the content. I do think having "Feature Request" documented on the issue is smart.
• There's probably room for issues that are useful but maybe not necessarily considered a "Feature". Maybe we need something else too? 🤔 I'll think this one over.

Simply use python target to create a venv.

Decide between using cargo doc or a similar tool. Add documentation on future inline comment expectations.

• Project architecture/design
• Project struct description and usage
• Venv struct description and usage
• Documenting future plans (what structs/ops will be added or fleshed out)
• Documentation on CONTRIBUTING expectations (every enhancement must have a test to cover it, etc.)
• #120
• #122

If a version isn't entered what do we default to? I usually see package managers use 0.1.0, but personally I like starting projects at a conservative 0.0.1.

Making prints pretty...

The interface part of CLI could be more appealing with colors and whatnot. Also loading animations would be cool. Stuff along these lines.

This is the tracking issue for the goals for Huak. All development should optimize to satisfy the goals listed here.

• Performance
• All-in-one - Huak should offer everything you need for standardized Python package maintenance. (huak test, huak fmt, huak lint, etc.)

• Project configuration specifically
• Manifest data
• Improve initialization of Project

This is not an exhaustive list. Just some low-hanging fruit.

Problem

Filesystem is challenging. Typically it involves tempdir testing. I know there are some projects we can use for this, but generally it seems pretty raw. We need to be able to execute commands within testing environments to ensure commands do what they are expected to do.

Solution

Use a tempdir testing facility along with clap testing to test commands. First pass to move towards TDD would be to at least start tempdir testing command operations implemented in Huak's lib.

huak install

Run huak install to create and setup a virtual environment for the project using an existing pyproject.toml.

The first iteration of this command will wrap pip to install the dependencies. If a virtual environment doesn't exist it will create one. No lockfile will exist yet.

Problem

Some projects offer highly interactive CLI appllications where the user can be prompted several times before completing a command's operation. Other projects are more streamlined to provide at least the base case, maybe making some assumptions, and completing a commands entire operation without prompting the user for any input. I'm a fan of some fairly interactive command-line tools such as GitHub CLI, Poetry, etc.. But I do also like the idea of becoming more streamlined, really leaning into the idea of being a snappy package manager and generalized dev tool.

Solution

I'm opening this issue up to track the decision. I'd prefer to poll this with Python users, but that's probably not efficient enough for a side-project like this. So I may end up choosing based on my own experience. As of the time of creating this issue I'm leaning towards limited interactivity.

Your issue may already be reported! Please check issue tracker before creating a new one.

Expected Behavior

An updated Markdown file that matches the template as expected.

Actual Behavior

A GitHub issue with these specifications.

Steps To Reproduce The Problem

1. Move to the "Issues" tab on GitHub and create a new issue
2. Select the "Bug report" template
3. Fill out the template.

Specifications

-Huak Version: 0.0.1
-Operating System: Windows 10

huak add

Run huak add to add a new dependency to the pyproject.toml and install it to a virtual environment.

The first iteration of this command would wrap pip to install the dependency and allow --dev to indicate it's a dev dependency. If a virtual environment doesn't exist then one will be generated.

https://github.com/huak-rs/triagebot

huak fix

Run huak fix to auto-fix lint conflicts in Python code.

The first version of fix would:

• Execute fixit from .venv

See fixit.

Instead of using fs_extra to copy mock directories to tempdirs for testing, we can just create our own dir copying function.

Add to huak::utils::path a function copy_dir to copy one directory into another target dir.

huak activate similar to poetry shell

For now I'm planning on setting the --test-threads param to 1 so that I can manipulate one .venv for testing.

I need to think about a better way to do it, so I'm leaving this issue open to track that.

The "basic" part of integrating with PyPI is probably the requests for metadata (or manifest data).