docs: add error codes + some cleanup (#367)

* docs: add error codes * docs(issues-detection): update transitive example * docs(usage): consistently move missing above obsolete * docs(usage): add error codes * docs(usage): remove legacy JSON output leftover
fpgmaas · May 8, 2023 · 8709b22 · 8709b22
1 parent eaf9546
commit 8709b22
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 62 deletions.
diff --git a/docs/issues-detection.md b/docs/issues-detection.md
@@ -2,90 +2,90 @@
 
 _deptry_ looks for the following issues in dependencies:
 
-- [Obsolete dependencies](#obsolete-dependencies)
-- [Missing dependencies](#missing-dependencies)
-- [Transitive dependencies](#transitive-dependencies)
-- [Misplaced development dependencies](#misplaced-development-dependencies)
+- [Missing dependencies (DEP001)](#missing-dependencies-dep001)
+- [Obsolete dependencies (DEP002)](#obsolete-dependencies-dep002)
+- [Transitive dependencies (DEP003)](#transitive-dependencies-dep003)
+- [Misplaced development dependencies (DEP004)](#misplaced-development-dependencies-dep004)
 
-## Obsolete dependencies
+## Missing dependencies (DEP001)
 
-Dependencies that are required in a project, but are not used within the codebase.
+Python modules that are imported within a project, for which no corresponding packages are found in the dependencies.
 
 ### Configuration
 
-This check can be disabled with [Skip obsolete](usage.md#skip-obsolete) option.
+This check can be disabled with [Skip missing](usage.md#skip-missing) option.
 
-Specific dependencies can be ignored with [Ignore obsolete](usage.md#ignore-obsolete) option.
+Specific dependencies can be ignored with [Ignore missing](usage.md#ignore-missing) option.
 
 ### Example
 
 On a project with the following dependencies:
 
 ```toml
 [project]
-dependencies = [
-    "httpx==0.23.1",
-    "requests==2.28.1",
-]
+dependencies = []
 ```
 
 and the following `main.py` that is the only Python file in the project:
 
 ```python
 import httpx
-import requests
 
 def make_http_request():
     return httpx.get("https://example.com")
 ```
 
-_deptry_ will report `requests` as an obsolete dependency because it is not used in the project.
+_deptry_ will report `httpx` as a missing dependency because it is imported in the project, but not defined in the dependencies.
 
-To fix the issue, `requests` should be removed from `[project.dependencies]`:
+To fix the issue, `httpx` should be added to `[project.dependencies]`:
 
 ```toml
 [project]
 dependencies = ["httpx==0.23.1"]
 ```
 
-## Missing dependencies
+## Obsolete dependencies (DEP002)
 
-Python modules that are imported within a project, for which no corresponding packages are found in the dependencies.
+Dependencies that are required in a project, but are not used within the codebase.
 
 ### Configuration
 
-This check can be disabled with [Skip missing](usage.md#skip-missing) option.
+This check can be disabled with [Skip obsolete](usage.md#skip-obsolete) option.
 
-Specific dependencies can be ignored with [Ignore missing](usage.md#ignore-missing) option.
+Specific dependencies can be ignored with [Ignore obsolete](usage.md#ignore-obsolete) option.
 
 ### Example
 
 On a project with the following dependencies:
 
 ```toml
 [project]
-dependencies = []
+dependencies = [
+    "httpx==0.23.1",
+    "requests==2.28.1",
+]
 ```
 
 and the following `main.py` that is the only Python file in the project:
 
 ```python
 import httpx
+import requests
 
 def make_http_request():
     return httpx.get("https://example.com")
 ```
 
-_deptry_ will report `httpx` as a missing dependency because it is imported in the project, but not defined in the dependencies.
+_deptry_ will report `requests` as an obsolete dependency because it is not used in the project.
 
-To fix the issue, `httpx` should be added to `[project.dependencies]`:
+To fix the issue, `requests` should be removed from `[project.dependencies]`:
 
 ```toml
 [project]
 dependencies = ["httpx==0.23.1"]
 ```
 
-## Transitive dependencies
+## Transitive dependencies (DEP003)
 
 Python modules that are imported within a project, where the corresponding dependencies are in the dependency tree, but not as direct dependencies.
 For example, assume your project has a `.py` file that imports module A. However, A is not in your project's dependencies. Instead, another package (B) is in your list of dependencies, which in turn depends on A. Package A should be explicitly added to your project's list of dependencies.
@@ -121,7 +121,7 @@ def get_certificates_location():
     return certifi.where()
 ```
 
-_deptry_ will report `certifi` as a transitive dependency because it is not used in the project.
+_deptry_ will report `certifi` as a transitive dependency because it is used in the project, but not defined as a direct dependency, and is only present in the dependency tree because another dependency depends on it.
 
 To fix the issue, `certifi` should be explicitly added to `[project.dependencies]`:
 
@@ -133,7 +133,7 @@ dependencies = [
 ]
 ```
 
-## Misplaced development dependencies
+## Misplaced development dependencies (DEP004)
 
 Dependencies specified as development ones that should be included as regular dependencies.
 

diff --git a/docs/usage.md b/docs/usage.md
@@ -154,45 +154,45 @@ extend_exclude = ["a_directory", "a_python_file\\.py", "a_pattern/.*"]
 deptry . --extend-exclude "a_directory|a_python_file\.py|a_pattern/.*"
 ```
 
-#### Ignore obsolete
+#### Ignore missing
 
-List of packages to ignore when running the check for [obsolete dependencies](issues-detection.md#obsolete-dependencies).
+List of Python modules to ignore when running the check for [Missing dependencies (DEP001)](issues-detection.md#missing-dependencies-dep001).
 
 - Type: `List[str]`
 - Default: `[]`
-- `pyproject.toml` option name: `ignore_obsolete`
-- CLI option name: `--ignore-obsolete` (short: `-io`)
+- `pyproject.toml` option name: `ignore_missing`
+- CLI option name: `--ignore-missing` (short: `-im`)
 - `pyproject.toml` example:
 ```toml
 [tool.deptry]
-ignore_obsolete = ["uvicorn", "uvloop"]
+ignore_missing = ["pip", "tomllib"]
 ```
 - CLI example:
 ```shell
-deptry . --ignore-obsolete "uvicorn,uvloop"
+deptry . --ignore-missing "pip,tomllib"
 ```
 
-#### Ignore missing
+#### Ignore obsolete
 
-List of Python modules to ignore when running the check for [missing dependencies](issues-detection.md#missing-dependencies).
+List of packages to ignore when running the check for [Obsolete dependencies (DEP002)](issues-detection.md#obsolete-dependencies-dep002).
 
 - Type: `List[str]`
 - Default: `[]`
-- `pyproject.toml` option name: `ignore_missing`
-- CLI option name: `--ignore-missing` (short: `-im`)
+- `pyproject.toml` option name: `ignore_obsolete`
+- CLI option name: `--ignore-obsolete` (short: `-io`)
 - `pyproject.toml` example:
 ```toml
 [tool.deptry]
-ignore_missing = ["pip", "tomllib"]
+ignore_obsolete = ["uvicorn", "uvloop"]
 ```
 - CLI example:
 ```shell
-deptry . --ignore-missing "pip,tomllib"
+deptry . --ignore-obsolete "uvicorn,uvloop"
 ```
 
 #### Ignore transitive
 
-List of Python modules to ignore when running the check for [transitive dependencies](issues-detection.md#transitive-dependencies).
+List of Python modules to ignore when running the check for [Transitive dependencies (DEP003)](issues-detection.md#transitive-dependencies-dep003).
 
 - Type: `List[str]`
 - Default: `[]`
@@ -210,7 +210,7 @@ deptry . --ignore-transitive "httpx,pip"
 
 #### Ignore misplaced dev
 
-List of Python modules to ignore when running the check for [misplaced development dependencies](issues-detection.md#misplaced-development-dependencies).
+List of Python modules to ignore when running the check for [Misplaced development dependencies (DEP004)](issues-detection.md#misplaced-development-dependencies-dep004).
 
 - Type: `List[str]`
 - Default: `[]`
@@ -244,45 +244,45 @@ ignore_notebooks = true
 deptry . --ignore-notebooks
 ```
 
-#### Skip obsolete
+#### Skip missing
 
-Disable the check for [obsolete dependencies](issues-detection.md#obsolete-dependencies).
+Disable the check for [Missing dependencies (DEP001)](issues-detection.md#missing-dependencies-dep001).
 
 - Type: `bool`
 - Default: `False`
-- `pyproject.toml` option name: `skip_obsolete`
-- CLI option name: `--skip-obsolete`
+- `pyproject.toml` option name: `skip_missing`
+- CLI option name: `--skip-missing`
 - `pyproject.toml` example:
 ```toml
 [tool.deptry]
-skip_obsolete = true
+skip_missing = true
 ```
 - CLI example:
 ```shell
-deptry . --skip-obsolete
+deptry . --skip-missing
 ```
 
-#### Skip missing
+#### Skip obsolete
 
-Disable the check for [missing dependencies](issues-detection.md#missing-dependencies).
+Disable the check for [Obsolete dependencies (DEP002)](issues-detection.md#obsolete-dependencies-dep002).
 
 - Type: `bool`
 - Default: `False`
-- `pyproject.toml` option name: `skip_missing`
-- CLI option name: `--skip-missing`
+- `pyproject.toml` option name: `skip_obsolete`
+- CLI option name: `--skip-obsolete`
 - `pyproject.toml` example:
 ```toml
 [tool.deptry]
-skip_missing = true
+skip_obsolete = true
 ```
 - CLI example:
 ```shell
-deptry . --skip-missing
+deptry . --skip-obsolete
 ```
 
 #### Skip transitive
 
-Disable the check for [transitive dependencies](issues-detection.md#transitive-dependencies).
+Disable the check for [Transitive dependencies (DEP003)](issues-detection.md#transitive-dependencies-dep003).
 
 - Type: `bool`
 - Default: `False`
@@ -300,7 +300,7 @@ deptry . --skip-transitive
 
 #### Skip misplaced dev
 
-Disable the check for [misplaced development dependencies](issues-detection.md#misplaced-development-dependencies).
+Disable the check for [Misplaced development dependencies (DEP004)](issues-detection.md#misplaced-development-dependencies-dep004).
 
 - Type: `bool`
 - Default: `False`
@@ -427,15 +427,6 @@ Write the detected issues to a JSON file. This will write the following kind of
 ]
 ```
 
-```json
-{
-    "obsolete": ["uvicorn", "uvloop"],
-    "missing": [],
-    "transitive": ["httpx"],
-    "misplaced_dev": ["black"]
-}
-```
-
 - Type: `Path`
 - Default: `None`
 - `pyproject.toml` option name: `json_output`