# auto-file-sorter
[](https://results.pre-commit.ci/latest/github/realshouzy/auto-file-sorter/main)
[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/pylint.yaml)
[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/tests.yaml)
[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/codeql.yaml)
[](https://github.com/realshouzy/auto-file-sorter/releases/latest)
[](https://pypi.org/project/auto-file-sorter/)
[](https://github.com/realshouzy/YTDownloader/releases)
[](https://pypi.org/project/auto-file-sorter/)
[](https://github.com/realshouzy/auto-file-sorter/blob/main/LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
**``auto-file-sorter`` is a Python automation tool that tracks a directory and sorts files into their respective folders based on their file extensions.**
## Installation
Make sure you have Python 3.9 or later installed. You can install the package using ``pip``:
```bash
pip install auto-file-sorter
```
Alternatively, you can install the package from GitHub to get the latest changes:
```bash
pip install git+https://github.com/realshouzy/auto-file-sorter.git
```
The project uses the following packages and libraries:
```python
# standard library
import argparse
import concurrent.futures
import datetime
import json
import logging
import os.path
import pathlib
import platform
import re
import shutil
import sys
import time
import typing
# third party
import typing_extensions
# import watchdog
import watchdog.events
import watchdog.observers
# only for type annotations; not used at runtime
import collections.abc
import watchdog.observers.api
# for testing
import pytest
```
## Documentation
Consult ``auto-file-sorter --help`` / ``auto-file-sorter -h`` for the full set of options. This also applies to all subcommands:
- ``auto-file-sorter track``
- ``auto-file-sorter read``
- ``auto-file-sorter write``
- ``auto-file-sorter locations``
### Arguments and flags of ``auto-file-sorter``
| Argument and flags | Use |
| -------- | ------- |
| ``--version`` / ``-V`` | Outputs the installed version of ``auto-file-sorter``. |
| ``--debug`` / ``-d`` | Sets the logging level to 10 (debugging), enabling more informative debugging logs. |
| ``--verbose`` / ``-v`` | Enables verbose outputs. It can be used up to three levels, with each level printing more logs to the stream. The first level prints all logs up to the logging level WARNING, the second level prints all logs up to INFO, and the third level prints all logs up to DEBUG (this requires the debugging flag). |
| ``--log-location`` | Specifies the path to a log file. By default, the log file will be located with the source code. |
| ``--configs-location`` | Specifies the path to the configs ``json`` file. By default, the configs file will be located with the source code. |
### Arguments and flags of ``auto-file-sorter track``
| Argument and flags | Use |
| -------- | ------- |
| Positional arguments | Paths to the directories to be tracked. At least one directory path must be provided. The tool will track all the given directories simultaneously using threading. |
| ``--undefined-extensions`` / ``-u`` | Path in which files whose extensions are not defined in the configs will be moved. If no path was specified, said files will be skipped. |
| ``--autostart`` (only supported on Windows) | Runs the command on startup. Refer to [Windows setup](#windows-setup) for more information. |
### Arguments of ``auto-file-sorter read``
| Argument | Use |
| -------- | ------- |
| Positional arguments | Extensions for which their respective paths should be read from the configs.json file. If no extensions are given, it will print out the entire ``configs.json`` file. |
### Arguments of ``auto-file-sorter write``
| Argument | Use |
| -------- | ------- |
| ``--add`` / ``-a`` | Adds an extension and its corresponding path to the ``configs.json`` file. It takes two arguments: the extension and the path to which files with this extension will be saved. If the extension already exists, the path will be overridden. |
| ``--remove`` / ``-r`` | Removes one or more extensions and their respective paths from the configuration. |
| ``--json`` / ``-j`` | Loads a ``json`` files that binds extensions to paths and merges it into the ``configs.json`` file. |
The json files should be structured similarly to the ``configs.json`` file. An example (with Windows paths) can be found in [``example_configs.json``](/example_configs.json).
Ultimately you can directly modify the ``configs.json`` file yourself.
### Flags of ``auto-file-sorter locations``
| Argument | Use |
| -------- | ------- |
| ``--log`` / ``-l`` | Prints the location of the log file |
| ``--config`` / ``-c`` | Prints the location of the config file |
## Run on startup
### Windows setup
To run the tool on startup, add the ``--autostart`` flag after the ``track`` subcommand. This will add the command to the Startup folder as a ``.vbs`` file, ensuring it runs in the background.
To avoid the overhead of creating a StreamHandler and prevent overwriting the ``.vbs`` file on every startup, it removes all occurrences of ``--verbose`` / ``-v`` as well as ``--autostart``.
An example of this transformation:
```diff
- auto-file-sorter -d -vvv track C:\path\to\be\tracked
+ C:\path\to\auto-file-sorter.exe -d track C:\path\to\be\tracked
```
This will then be run by the ``.vbs`` file on startup:
```vbs
Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run "C:\path\to\auto-file-sorter.exe -d track C:\path\to\be\tracked", 0, True
```
### macOS setup
Add the desired command to the ``Automator`` app. You can find a tutorial [here](https://youtu.be/LfxZMofHs_U?t=658).
### Linux setup
Due to the wide variety of Linux distributions and their differences, it is up to the user to configure ``auto-file-sorter`` to run on startup.
## Usage
Simply place files into the tracked folder, and the tool will automatically sort them for you.
## Excpetion handling
Most exceptions will be logged in a log file. If an exception should occur, the program will handle it gracefuly by exiting with exit code 1, except in cases where an exception is encountered while moving a file. This behavior is specifically implemented to address threading concerns and ensure proper garbage collection. In such cases, the respective thread will exit, while the main program continues its execution. Ultimately, the user has the option to stop the program manually. This approach allows for proper cleanup and termination of resources.
## Contributing
If you are interested in contributing to this project, please refer [here](https://github.com/realshouzy/auto-file-sorter/blob/main/CONTRIBUTING.md) for more information.
## License
``auto-file-sorter`` is available under the [MIT license](https://github.com/realshouzy/auto-file-sorter/blob/main/LICENSE)
## Credit
This project was originally inspired by Kalle Hallden's [desktop_cleaner](https://github.com/KalleHallden/desktop_cleaner) project.
Raw data
{
"_id": null,
"home_page": "",
"name": "auto-file-sorter",
"maintainer": "realshouzy",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "automation,file,sorter,auto,watchdog",
"author": "realshouzy",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0e/63/a30aa90153b83d13dbdb66656de33161721948a79eb95549fcd247dbd8f6/auto-file-sorter-1.0.2.tar.gz",
"platform": null,
"description": "# auto-file-sorter\n\n[](https://results.pre-commit.ci/latest/github/realshouzy/auto-file-sorter/main)\n[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/pylint.yaml)\n[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/tests.yaml)\n[](https://github.com/realshouzy/auto-file-sorter/actions/workflows/codeql.yaml)\n[](https://github.com/realshouzy/auto-file-sorter/releases/latest)\n[](https://pypi.org/project/auto-file-sorter/)\n[](https://github.com/realshouzy/YTDownloader/releases)\n[](https://pypi.org/project/auto-file-sorter/)\n[](https://github.com/realshouzy/auto-file-sorter/blob/main/LICENSE)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n\n**``auto-file-sorter`` is a Python automation tool that tracks a directory and sorts files into their respective folders based on their file extensions.**\n\n## Installation\n\nMake sure you have Python 3.9 or later installed. You can install the package using ``pip``:\n\n```bash\npip install auto-file-sorter\n```\n\nAlternatively, you can install the package from GitHub to get the latest changes:\n\n```bash\npip install git+https://github.com/realshouzy/auto-file-sorter.git\n```\n\nThe project uses the following packages and libraries:\n\n```python\n# standard library\nimport argparse\nimport concurrent.futures\nimport datetime\nimport json\nimport logging\nimport os.path\nimport pathlib\nimport platform\nimport re\nimport shutil\nimport sys\nimport time\nimport typing\n\n# third party\nimport typing_extensions\n# import watchdog\nimport watchdog.events\nimport watchdog.observers\n\n# only for type annotations; not used at runtime\nimport collections.abc\nimport watchdog.observers.api\n\n# for testing\nimport pytest\n```\n\n## Documentation\n\nConsult ``auto-file-sorter --help`` / ``auto-file-sorter -h`` for the full set of options. This also applies to all subcommands:\n\n- ``auto-file-sorter track``\n- ``auto-file-sorter read``\n- ``auto-file-sorter write``\n- ``auto-file-sorter locations``\n\n### Arguments and flags of ``auto-file-sorter``\n\n| Argument and flags | Use |\n| -------- | ------- |\n| ``--version`` / ``-V`` | Outputs the installed version of ``auto-file-sorter``. |\n| ``--debug`` / ``-d`` | Sets the logging level to 10 (debugging), enabling more informative debugging logs. |\n| ``--verbose`` / ``-v`` | Enables verbose outputs. It can be used up to three levels, with each level printing more logs to the stream. The first level prints all logs up to the logging level WARNING, the second level prints all logs up to INFO, and the third level prints all logs up to DEBUG (this requires the debugging flag). |\n| ``--log-location`` | Specifies the path to a log file. By default, the log file will be located with the source code. |\n| ``--configs-location`` | Specifies the path to the configs ``json`` file. By default, the configs file will be located with the source code. |\n\n### Arguments and flags of ``auto-file-sorter track``\n\n| Argument and flags | Use |\n| -------- | ------- |\n| Positional arguments | Paths to the directories to be tracked. At least one directory path must be provided. The tool will track all the given directories simultaneously using threading. |\n| ``--undefined-extensions`` / ``-u`` | Path in which files whose extensions are not defined in the configs will be moved. If no path was specified, said files will be skipped. |\n| ``--autostart`` (only supported on Windows) | Runs the command on startup. Refer to [Windows setup](#windows-setup) for more information. |\n\n### Arguments of ``auto-file-sorter read``\n\n| Argument | Use |\n| -------- | ------- |\n| Positional arguments | Extensions for which their respective paths should be read from the configs.json file. If no extensions are given, it will print out the entire ``configs.json`` file. |\n\n### Arguments of ``auto-file-sorter write``\n\n| Argument | Use |\n| -------- | ------- |\n| ``--add`` / ``-a`` | Adds an extension and its corresponding path to the ``configs.json`` file. It takes two arguments: the extension and the path to which files with this extension will be saved. If the extension already exists, the path will be overridden. |\n| ``--remove`` / ``-r`` | Removes one or more extensions and their respective paths from the configuration. |\n| ``--json`` / ``-j`` | Loads a ``json`` files that binds extensions to paths and merges it into the ``configs.json`` file. |\n\nThe json files should be structured similarly to the ``configs.json`` file. An example (with Windows paths) can be found in [``example_configs.json``](/example_configs.json).\nUltimately you can directly modify the ``configs.json`` file yourself.\n\n### Flags of ``auto-file-sorter locations``\n\n| Argument | Use |\n| -------- | ------- |\n| ``--log`` / ``-l`` | Prints the location of the log file |\n| ``--config`` / ``-c`` | Prints the location of the config file |\n\n## Run on startup\n\n### Windows setup\n\nTo run the tool on startup, add the ``--autostart`` flag after the ``track`` subcommand. This will add the command to the Startup folder as a ``.vbs`` file, ensuring it runs in the background.\n\nTo avoid the overhead of creating a StreamHandler and prevent overwriting the ``.vbs`` file on every startup, it removes all occurrences of ``--verbose`` / ``-v`` as well as ``--autostart``.\n\nAn example of this transformation:\n\n```diff\n- auto-file-sorter -d -vvv track C:\\path\\to\\be\\tracked\n+ C:\\path\\to\\auto-file-sorter.exe -d track C:\\path\\to\\be\\tracked\n```\n\nThis will then be run by the ``.vbs`` file on startup:\n\n```vbs\nSet objShell = WScript.CreateObject(\"WScript.Shell\")\nobjShell.Run \"C:\\path\\to\\auto-file-sorter.exe -d track C:\\path\\to\\be\\tracked\", 0, True\n```\n\n### macOS setup\n\nAdd the desired command to the ``Automator`` app. You can find a tutorial [here](https://youtu.be/LfxZMofHs_U?t=658).\n\n### Linux setup\n\nDue to the wide variety of Linux distributions and their differences, it is up to the user to configure ``auto-file-sorter`` to run on startup.\n\n## Usage\n\nSimply place files into the tracked folder, and the tool will automatically sort them for you.\n\n## Excpetion handling\n\nMost exceptions will be logged in a log file. If an exception should occur, the program will handle it gracefuly by exiting with exit code 1, except in cases where an exception is encountered while moving a file. This behavior is specifically implemented to address threading concerns and ensure proper garbage collection. In such cases, the respective thread will exit, while the main program continues its execution. Ultimately, the user has the option to stop the program manually. This approach allows for proper cleanup and termination of resources.\n\n## Contributing\n\nIf you are interested in contributing to this project, please refer [here](https://github.com/realshouzy/auto-file-sorter/blob/main/CONTRIBUTING.md) for more information.\n\n## License\n\n``auto-file-sorter`` is available under the [MIT license](https://github.com/realshouzy/auto-file-sorter/blob/main/LICENSE)\n\n## Credit\n\nThis project was originally inspired by Kalle Hallden's [desktop_cleaner](https://github.com/KalleHallden/desktop_cleaner) project.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A file sorting automation",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/realshouzy/auto-file-sorter/commits/",
"Documentation": "https://github.com/realshouzy/auto-file-sorter/blob/main/README.md#documentation",
"Issues": "https://github.com/realshouzy/auto-file-sorter/issues",
"Repository": "https://github.com/realshouzy/auto-file-sorter"
},
"split_keywords": [
"automation",
"file",
"sorter",
"auto",
"watchdog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "015c3441fef3de49a0edc484a4bc088d858eb5b5f2a51b7b5574be6c23d2f502",
"md5": "097105a4c5f5abba6e6bb8f57a065700",
"sha256": "ce685d2e777720bf9463e855e188793e089f2642b59053125891daf6a13226b4"
},
"downloads": -1,
"filename": "auto_file_sorter-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "097105a4c5f5abba6e6bb8f57a065700",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16413,
"upload_time": "2024-01-14T00:05:15",
"upload_time_iso_8601": "2024-01-14T00:05:15.355873Z",
"url": "https://files.pythonhosted.org/packages/01/5c/3441fef3de49a0edc484a4bc088d858eb5b5f2a51b7b5574be6c23d2f502/auto_file_sorter-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e63a30aa90153b83d13dbdb66656de33161721948a79eb95549fcd247dbd8f6",
"md5": "6a25561840be61212a8a9b13a436ba8a",
"sha256": "e2cc22f58b100b1e3c43edcef12fe57e428de4f7448281ccfacfabc551c14281"
},
"downloads": -1,
"filename": "auto-file-sorter-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6a25561840be61212a8a9b13a436ba8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17037,
"upload_time": "2024-01-14T00:05:17",
"upload_time_iso_8601": "2024-01-14T00:05:17.111723Z",
"url": "https://files.pythonhosted.org/packages/0e/63/a30aa90153b83d13dbdb66656de33161721948a79eb95549fcd247dbd8f6/auto-file-sorter-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-14 00:05:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "realshouzy",
"github_project": "auto-file-sorter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "auto-file-sorter"
}
JSON
