Add user-configurable categories via TOML config

[AzisK]

Introduces support for customizing file categories and extensions through a user-defined ~/.zpace.toml file. Adds a sample configuration file, updates documentation and changelog, removes Fonts from default categories, and implements logic in config.py to merge user settings with defaults. Also adds comprehensive unit tests for configuration loading and updates dependencies to include tomli for Python <3.11.

Features

• User Configuration: Added support for customizing file categories via ~/.zpace.toml
  • extensions: Replace all extensions for a category
  • add: Add extensions to an existing category
  • remove: Remove extensions from a category
  • Create entirely new custom categories
• Added .zpace.toml.sample template file

Configuration

• Removed "Fonts" from default categories (can be re-added via user config)

Documentation

• Added Configuration section to README with examples
• Moved Changelog and Architecture links to new Docs section

[github-actions]

⸜(｡˃ ᵕ ˂ )⸝♡ Thank you for opening this Pull Request, AzisK!

( ˶°ㅁ°) !! It's Trivia Time!

Here are 3 trivia questions to keep you entertained while CI runs.
(Feel free to demonstrate your knowledge and reply!)

🧩 Q1: When was Cadillac founded?

A) 1964
B) 1902
C) 1985
D) 1898

🧩 Q2: Who was world chess champion between 1894 and 1921

A) José Raúl Capablanca
B) Wilhelm Steinitz
C) Bobby Fischer
D) Emanuel Lasker

🧩 Q3: What is a Burgee?

A) A window
B) A type of food
C) A flag
D) A rope

You got this! Remember, every bug is just a feature in disguise.

[github-actions]

Code Review

1. New Features

• Support for custom categories via :
  • This is an excellent and thoughtful addition to the project, as it brings much-needed flexibility for users to define their file categories. Introducing TOML as the configuration format is a smart choice because of its readability and nesting capabilities, especially for developers.
  • The example file is clean, concise, and provides thorough documentation for new and advanced users alike. Nicely done including comprehensive examples of common use cases like custom categories, file type additions, and extensions removals.
  • Removing the Fonts category from defaults but ensuring it can be re-added through configuration adds flexibility without cluttering the default experience.

2. Implementation Details

• ** Logic (Lines 300–340 in ):**

  • The logic to merge the user-defined categories with default categories is implemented sensibly and avoids destructive operations by copying the dictionary on initialization. This ensures the original defaults remain untouched even if loaded using customized configurations — which is an excellent design choice and guarantees immutability of global shared variables. 👏

  • The use of for TOML parsing adheres to modern Python standards. Providing fallback support using for older versions of Python is an excellent design choice—great job maintaining backward compatibility. 😄

  • The handling of key edge cases (e.g., missing/malformed , or trying to add/remove extensions for non-existent categories) is solid. However, it's worth considering leveraging an instead of silent failure when handling exceptions (e.g., in cases of a malformed TOML file—Line 323). This could provide helpful feedback to users and developers debugging the issue.

    Suggested Improvement: On Line 321–322, add a call (assuming there's existing logging in the project; if not, consider adding it). For example:

    This modification will help track issues with user-supplied TOML configs without failing silently.

• Immutable Default Categories (Line 303):

  • Nice touch to prevent direct mutation of via a dictionary copy when initializing . This level of attention to detail helps with debugging and ensures consistency between default values and their usage in runtime.

3. Unit Tests (Lines 760–865 in ):

• The test suite for the new feature is comprehensive and thorough. You've verified all expected behaviors, including:
  • Missing or empty config file scenarios ( and ).
  • Add, remove, and replace operations for existing categories (, , ).
  • Handling complex modifications (combined operations) and creating new custom categories (, ).
  • Ensuring no mutation of during runtime ().
  • The test for improper TOML is a particularly good example of defensive programming! 👍
• Test case descriptions are clear and document exactly what was tested and expected.
• Your use of to mock the underlying filesystem () minimizes dependencies on the actual environment and is an excellent choice for robust, isolated unit testing. Great job!
• One small improvement for readability: instead of repeating string literals in each test case for TOML configurations like , you could use constants or small pre-defined snippets (e.g., ).

4. Updates to Documentation (README and CHANGELOG)

• The added examples in the Configuration section of the README are excellent and well-written. Using both explanatory comments and TOML snippets ensures that both beginners and experienced developers will understand the functionality easily. Great job! 👏
• Ensuring that is both instruction-friendly and easy to use as a basis is great for user onboarding.
• Moving the and links to a dedicated section makes the README look more organized and structured. Adding instructions for configuration in this update demonstrates proper user-centric thinking. Kudos for putting thought into user experience! 🌟

5. Dependency Updates (pyproject.toml and ):

• Adding as a conditional dependency for systems running earlier versions of Python is an excellent inclusion. You've covered a wide range of Python versions (3.9+). 🎉
• You could consider adding a file or mentioning these requirements prominently somewhere to help developers understand dependency reasoning. However, this isn't strictly mandatory since TOML is widely used and easy to understand.

6. Miscellaneous:

• Line 340 ( within ):
  • Placing the merge result into a global variable could introduce potential issues if users modify the global variable during runtime (e.g., if other parts of the program or third-party plugins modify the variable without reloading the configuration file). While this might not be a current concern, it’s something to be aware of for future extensibility. You could mitigate this with a mechanism for reloading the config whenever needed, such as providing a function designed for this.

Summary

This is an extremely well-executed PR! You’ve clearly thought through multiple edge cases, provided a complete set of unit tests, implemented well-written and highly readable code, maintained backward compatibility, and updated documentation for user friendliness.

Minimal improvements to consider:

1. Introduce log warnings for misconfigured or invalid TOML files (Line 321–322).
2. Consider using a function to explicitly reload configurations to protect global values against accidental runtime modification.

Great work! This will significantly enhance the usability of Zpace. Keep up the excellent work; your thoroughness and attention to detail really set you apart! 🚀

[github-actions]

🎉 All tests passed! Here's a dog for you! 🐶