Merge pull request #87 from MiWeiss/deprecate-ignore-file

Deprecate old config file

Author: HunterMcGushion

README.md

@@ -92,16 +92,6 @@ docstr-coverage some_project/src
   - 3 - Also print missing docstrings (function names, class names, etc.)
   - 4 - Also print information about present docstrings
 - _--fail-under=<int|float>, -F <int|float>_ - Fail if under a certain percentage of coverage (default: 100.0)
-- _--docstr-ignore-file=\<filepath\>, -d \<filepath\>_ - Filepath containing list of patterns to ignore. Patterns are (file-pattern, name-pattern) pairs
-  - File content example:
-
-  ```
-  SomeFile method_to_ignore1 method_to_ignore2 method_to_ignore3
-  FileWhereWeWantToIgnoreAllSpecialMethods __.+__
-  .* method_to_ignore_in_all_files
-  a_very_important_view_file ^get$ ^set$ ^post$
-  detect_.* get_val.*
-  ```
 - _--badge=\<filepath\>, -b \<filepath\>_ - Generate a docstring coverage percent badge as an SVG saved to a given filepath
   - Include the badge in a repo's README using 
   ```[![docstr_coverage](<filepath/of/your/saved/badge.svg>)](https://github.com/HunterMcGushion/docstr_coverage)```,
@@ -152,8 +142,10 @@ docstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="d
 
 Note that options passed as command line arguments have precedence over options 
 configured in a config file.
-Exception: If a `--docstr-ignore-file` is present and the yml config contains `ignore_patterns`,
-a `ValueError` is raised.
+
+#### Ignoring by Regex
+In your config files, using `ignore_patterns`, you can specify regex patterns for files names and nodes (methods, ...)
+which should be ignored. See config file example above.
 
 #### Overriding by Comments
 Note that `docstr-coverage` can not parse 

docstr_coverage/cli.py

@@ -202,15 +202,6 @@ def _assert_valid_key_value(k, v):
     help="Ignore docstrings of functions starting with a single underscore",
 )
 @click.option("-l", "--follow-links", is_flag=True, help="Follow symlinks")
-@click.option(
-    "-d",
-    "--docstr-ignore-file",
-    "ignore_names_file",  # TODO: Remove after deprecating in favor of pyproject.toml `blacklist`
-    type=click.Path(exists=False, resolve_path=True),
-    default=".docstr_coverage",
-    help="Filepath containing list of regex (file-pattern, name-pattern) pairs",
-    show_default=True,
-)
 @click.option(
     "-F",
     "--fail-under",
@@ -262,25 +253,18 @@ def _assert_valid_key_value(k, v):
 @click.option("--skipclassdef", is_flag=True, help="Deprecated. Use --skip-class-def")
 @click.option("--followlinks", is_flag=True, help="Deprecated. Use --follow-links")
 @click.option("--failunder", type=float, help="Deprecated. Use --fail-under")
+@click.option(
+    "-d",
+    "--docstr-ignore-file",
+    "ignore_names_file",
+    type=click.Path(exists=False, resolve_path=True),
+    default=".docstr_coverage",
+    help="Deprecated. Use json config (--config / -C) instead",
+)
 def execute(paths, **kwargs):
     """Measure docstring coverage for `PATHS`"""
-    for deprecated_name, name in [
-        ("skipmagic", "skip_magic"),
-        ("skipfiledoc", "skip_file_doc"),
-        ("skipinit", "skip_init"),
-        ("skipclassdef", "skip_class_def"),
-        ("followlinks", "follow_links"),
-    ]:
-        if kwargs.get(deprecated_name):
-            new_flag = name.replace("_", "-")
-            if kwargs.get(name):
-                raise ValueError(
-                    "Should not set deprecated --{} and new --{}".format(deprecated_name, new_flag)
-                )
-            click.secho(
-                "Using deprecated --{}, should use --{}".format(deprecated_name, new_flag), fg="red"
-            )
-            kwargs[name] = kwargs.pop(deprecated_name)
+
+    _deprecation_alerts(kwargs)
 
     # handle fail under
     if kwargs.get("failunder") is not None:
@@ -317,7 +301,7 @@ def execute(paths, **kwargs):
         raise ValueError(
             (
                 "The docstr-coverage configuration file {} contains ignore_patterns,"
-                " and at the same time an ignore file {} was found."
+                " and at the same time a (deprecated) ignore file {} was found."
                 " Ignore patterns must be specified in only one location at a time."
             ).format(kwargs["config_file"], kwargs["ignore_names_file"])
         )
@@ -366,5 +350,45 @@ def execute(paths, **kwargs):
     raise SystemExit(0)
 
 
+def _deprecation_alerts(kwargs):
+    """Warns users if they are using deprecated flags"""
+    for deprecated_name, name in [
+        ("skipmagic", "skip_magic"),
+        ("skipfiledoc", "skip_file_doc"),
+        ("skipinit", "skip_init"),
+        ("skipclassdef", "skip_class_def"),
+        ("followlinks", "follow_links"),
+    ]:
+        if kwargs.get(deprecated_name):
+            new_flag = name.replace("_", "-")
+            if kwargs.get(name):
+                raise ValueError(
+                    "Should not set deprecated --{} and new --{}".format(deprecated_name, new_flag)
+                )
+            click.secho(
+                "Using deprecated --{}, should use --{}".format(deprecated_name, new_flag), fg="red"
+            )
+            kwargs[name] = kwargs.pop(deprecated_name)
+
+    # Deprecated old ignore files
+    ignore_file_old_casing = kwargs.get("docstr-ignore-file")
+    ignore_file_new_casing = kwargs.get("ignore_names_file")
+
+    def _nondefault_or_existing_file(path):
+        if path is None:
+            return False
+        return os.path.split(path)[-1] != ".docstr_coverage" or os.path.isfile(path)
+
+    if _nondefault_or_existing_file(ignore_file_old_casing) or _nondefault_or_existing_file(
+        ignore_file_new_casing
+    ):
+        click.secho(
+            "Using deprecated ignore files."
+            "We'll keep them supported for a while, "
+            "but we recommend switching to a proper config file "
+            "(see commands -C / --config)"
+        )
+
+
 if __name__ == "__main__":
     execute()