Merge pull request #1 from fpgmaas/docs

added documentation, also added some common known packages to import_…

README.md

@@ -29,7 +29,7 @@ __deptry__ can be added to your project with
 poetry add deptry
 ```
 
-Alternatively, it can be installed with `pip install deptry`, but since configuration is set within __pyproject.toml__, this is not recommended.
+Alternatively, it can be installed with `pip install deptry`.
 
 ### Prerequisites
 

deptry/import_parser.py

@@ -28,7 +28,7 @@ def get_imported_modules_for_file(self, path_to_py_file: Path) -> List[str]:
             logging.debug(f"Found the following imports in {str(path_to_py_file)}: {modules}")
             return modules
         except:  # noqa
-            logging.warn(f"Warning: Parsing imports for file {str(path_to_py_file)} failed.")
+            logging.warning(f"Warning: Parsing imports for file {str(path_to_py_file)} failed.")
 
     def get_imported_modules_for_list_of_files(self, list_of_paths: List[Path]) -> List[str]:
         modules_per_file = [

deptry/imports_to_package_names.py

@@ -8,6 +8,8 @@
 from isort.stdlibs.py39 import stdlib as stdlib39
 from isort.stdlibs.py310 import stdlib as stdlib310
 
+COMMON_PACKAGES_WITHOUT_METADATA = {"bs4": "beautifulsoup4", "dotenv": "python-dotenv"}
+
 
 class ImportsToPackageNames:
     """
@@ -32,14 +34,16 @@ def convert(self, imported_modules: List[str]):
             except:  # noqa
                 if module in self._get_stdlib_packages():
                     logging.debug(f"module {module} is in the Python standard library.")
+                elif module in COMMON_PACKAGES_WITHOUT_METADATA.keys():
+                    packages.append(COMMON_PACKAGES_WITHOUT_METADATA[module])
                 else:
-                    logging.warn(f"Warning: Failed to find corresponding package name for import {module}")
+                    logging.warning(f"Warning: Failed to find corresponding package name for import {module}")
 
         if len(packages) == 0:
-            logging.warn(
+            logging.warning(
                 "Warning: No metadata was found for any of the imported modules. This can simply be because the package only uses the Python standard library,"
             )
-            logging.warn(
+            logging.warning(
                 "but this can also be caused by the environment not being installed, found, or activated. Run `deptry check` with the `-v` flag for more details."
             )
         logging.debug("\n")

docs/index.md

@@ -1,8 +1,50 @@
+
 # deptry
 
+
 [![Release](https://img.shields.io/github/v/release/fpgmaas/deptry)](https://img.shields.io/github/v/release/fpgmaas/deptry)
 [![Build status](https://img.shields.io/github/workflow/status/fpgmaas/deptry/merge-to-main)](https://img.shields.io/github/workflow/status/fpgmaas/deptry/merge-to-main)
 [![Commit activity](https://img.shields.io/github/commit-activity/m/fpgmaas/deptry)](https://img.shields.io/github/commit-activity/m/fpgmaas/deptry)
+[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://fpgmaas.github.io/deptry/)
+[![Code style with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports with isort](https://img.shields.io/badge/%20imports-isort-%231674b1)](https://pycqa.github.io/isort/)
 [![License](https://img.shields.io/github/license/fpgmaas/deptry)](https://img.shields.io/github/license/fpgmaas/deptry)
 
-A repository to check for unused dependencies in a poetry managed python project
+---
+
+_deptry_ is a command line tool to check for unused dependencies in a poetry managed python project. It does so by scanning the imported modules within all `.py` files in 
+a directory and it's subdirectories, and comparing those to the dependencies listed in `pyproject.toml`. 
+
+## Installation and usage
+
+### Installation
+
+_deptry_ can be added to your project with 
+
+```
+poetry add deptry
+```
+
+Alternatively, it can be installed with `pip install deptry`.
+
+### Prerequisites
+
+In order to check for obsolete imports, _deptry_ should be run directly within the directory that contains the _pyproject.toml_ file, and it requires the environment created with _pyproject.toml_ to be activated.
+
+### Usage
+
+To scan your project for obsolete imports, run
+
+```sh
+deptry check
+```
+
+which might output:
+
+```
+pyproject.toml contains obsolete dependencies: ['pandas', 'numpy']
+```
+
+_deptry_ can be configured by using additional command line arguments, or 
+by adding a `[tool.deptry]` section in _pyproject.toml_. For more information, see the [Usage and Configuration](./usage.md)
+

docs/usage.md

@@ -0,0 +1,71 @@
+# Usage & Configuration
+
+## Prerequisites
+
+In order to check for obsolete imports, _deptry_ should be run directly within the directory that contains the _pyproject.toml_ file, and it requires the environment created with _pyproject.toml_ to be activated.
+
+## Basic Usage
+
+_deptry_ can be run with
+
+```sh
+deptry check
+```
+
+which might output the following:
+
+```
+pyproject.toml contains obsolete dependencies: ['pandas', 'numpy']
+```
+
+## Increased verbosity
+
+To show more details about the scanned python files, the imported modules found, and how deptry determined which dependencies are obsolete, add the `-v` flag:
+
+```sh
+deptry check -v
+```
+
+## Ignore dependencies
+
+Sometimes, you might want _deptry_ to ignore certain dependencies, for example when you have an module that is used but not imported, or when _deptry_
+incorrectly marks a dependency as obsolete. Dependencies can be ignore with the `-i` flag:
+
+```sh
+deptry check -i pandas
+```
+
+Multiple dependencies can be ignored by using the flag multiple times:
+
+```sh
+deptry check -i pandas -i numpy
+```
+
+## Ignore directories
+
+_deptry_ scans the working directory and it's subdirectories recursively for `.py` files to scan for import statements. By default,
+the `.venv` directory is ignored. To ignore other directories, use the `-id` flag. Note that this overwrites the default, so to ignore
+both the `.venv` directory and another directory, use the flag twice:
+
+```sh
+deptry check -id .venv -id other_directory
+```
+
+## pyproject.toml
+
+_deptry_ can also be configured through `pyproject.toml`. An example `pyproject.toml` entry for `deptry` looks as follows:
+
+```toml
+[tool.deptry]
+ignore_dependencies = [
+'pandas'
+]
+ignore_directories = [
+'.venv',
+'other_directory'
+]
+```
+
+## Lookup hierarchy
+
+Command-line options have defaults that you can see in --help. A pyproject.toml can override those defaults. Finally, options provided by the user on the command line override both.

mkdocs.yml

@@ -1,21 +1,15 @@
 site_name: deptry
 repo_url: https://github.com/fpgmaas/deptry
 site_url: https://fpgmaas.github.io/deptry
-site_description: A repository to check for unused dependencies in a poetry managed python project
+site_description: A command line tool to check for unused dependencies in a poetry managed python project.
 site_author: Florian Maas
 
 nav:
   - Home: index.md
-  - Modules: modules.md
+  - Usage and Configuration: usage.md
 plugins:
   - search
-  - mkdocstrings:
-      handlers:
-        python:
-            setup_commands:
-                - import sys
-                - sys.path.append('../')
-copyright: Maintained by Florian Maas.
+copyright: Maintained by <a href="https://fpgmaas.com">Florian</a>.
 theme:
   name: material
   feature:

tests/test_imports_to_package_names.py

@@ -0,0 +1,19 @@
+from deptry.imports_to_package_names import ImportsToPackageNames
+
+
+def test_simple_import():
+    imported_modules = ["click"]
+    package_names = ImportsToPackageNames().convert(imported_modules)
+    assert package_names == ["click"]
+
+
+def test_common_exception():
+    imported_modules = ["bs4"]
+    package_names = ImportsToPackageNames().convert(imported_modules)
+    assert package_names == ["beautifulsoup4"]
+
+
+def test_stdlib():
+    imported_modules = ["sys"]
+    package_names = ImportsToPackageNames().convert(imported_modules)
+    assert package_names == []