Merge branch 'release/0.1.1'

.github/actions/doctest/action.yaml

@@ -0,0 +1,18 @@
+name: Doctest
+inputs:
+  working_directory:
+    required: true
+    description: Directory containing the Makefile
+runs:
+  using: composite
+  steps:
+    - name: Run doctests
+      shell: bash
+      working-directory: ${{ inputs.working_directory }}
+      run: |
+        set -exuo pipefail
+
+        cd docs
+        make clean
+        make html
+        make doctest

.github/workflows/pyright.yaml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          python-version: 3.9
       - name: Cache pip
         uses: actions/cache@v2
         with:
@@ -31,3 +31,6 @@ jobs:
       - uses: ./.github/actions/pyright
         with:
           working_directory: ${{ github.workspace }}
+      - uses: ./.github/actions/doctest
+        with:
+          working_directory: ${{ github.workspace }}

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 default_language_version:
-    python: python3.8
+    python: python3
 repos:
 -   repo: https://github.com/google/yapf
     rev: v0.32.0
@@ -34,7 +34,7 @@ repos:
         language: node
         types: [python]
         pass_filenames: false
-        additional_dependencies: ["pyright"]
+        additional_dependencies: ["pyright@1.1.243"]
 # -   repo: https://github.com/PyCQA/pydocstyle
 #     hooks:
 #     -   id: pydocstyle

docs/source/api_ref/create.rst

@@ -0,0 +1,5 @@
+Create Object
+=============
+
+.. automodule:: yahp.create_object.create_object
+    :members:

docs/source/conf.py

@@ -30,9 +30,11 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.extlinks',
     'sphinx.ext.coverage',
+    'sphinx.ext.doctest',
     'sphinx.ext.napoleon',
     'sphinxcontrib.katex',
     'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
     'sphinxext.opengraph',
     'sphinx_copybutton',
     'sphinx_rtd_theme',
@@ -64,3 +66,11 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
+
+autosectionlabel_prefix_document = True
+autosummary_imported_members = False
+autosectionlabel_maxdepth = 5
+autosummary_generate = True
+
+# html_static_path = ['_static']
+html_title = ' YAHP'

docs/source/index.rst

@@ -22,6 +22,7 @@ YAHP
    :caption: API Reference
 
    api_ref/hparams
+   api_ref/create
    api_ref/field
    api_ref/inheritance
    api_ref/types

meta.yaml

@@ -2,12 +2,12 @@
 
 package:
   name: yahp
-  version: "0.1.0"
+  version: "0.1.1"
 
 source:
   git_url: https://github.com/mosaicml/yahp.git
-  git_rev: v0.1.0
-  git_depth: 1
+  git_rev: v0.1.1
+  git_depth: -1
 
 channels:
   - defaults
@@ -21,6 +21,10 @@ build:
 requirements:
   host:
     - python >=3.7
+    - setuptools
+    - git
+  build:
+    - git
   run:
     - python >=3.7
     - pyyaml >=5.4.1

pyproject.toml

@@ -52,6 +52,7 @@ reportUnusedCoroutine = "error"
 filterwarnings = [
     "error",
     "ignore:ExtraArgumentWarning",
+    '''ignore:.*validate\(\) is deprecated:DeprecationWarning''',
 ]
 
 # Coverage

setup.py

@@ -8,10 +8,7 @@
 
 exec(open('yahp/version.py', 'r', encoding='utf-8').read())
 
-install_requires = [
-    'PyYAML>=5.4.1',
-    'ruamel.yaml>=0.17.10',
-]
+install_requires = ['PyYAML>=5.4.1', 'ruamel.yaml>=0.17.10', 'docstring_parser>=0.14.1,<=0.15']
 
 extra_deps = {}
 

tests/fixtures/commented_map.yaml

@@ -135,7 +135,7 @@ optional_bool_field_default_true: true
 #       Optional[bool] (Optional). Description: optional bool field default None. Defaults to None.
 optional_bool_field_default_none:
 # Optional[DummyEnum{RED, GREEN, blue}] (Optional). Description: optional enum field default red.
-optional_enum_field_default_red: red
+optional_enum_field_default_red: RED
 # Optional[DummyEnum{RED, GREEN, blue}] (Optional). Description: optional enum field default None. Defaults to None.
 optional_enum_field_default_none:
 # Optional[bool | str] (Optional). Description: optional union_bool_str field default True.

tests/test_auto_field.py

@@ -0,0 +1,112 @@
+from typing import Callable
+from unittest.mock import Mock
+
+import docstring_parser
+import pytest
+
+import yahp as hp
+import yahp.field
+
+
+class FooClassDocstring:
+    """Foo class
+
+    Args:
+        required (str): Required parameter.
+        optional (int, optional): Optional parameter. (default: ``5``)
+    """
+
+    def __init__(self, required: str, optional: int = 5):
+        self.required = required
+        self.optional = optional
+
+
+class FooClassAndInitDocstring:
+    """Foo class.
+    """
+
+    def __init__(self, required: str, optional: int = 5):
+        """Foo init.
+
+        Args:
+            required (str): Required parameter.
+            optional (int, optional): Optional parameter. (default: ``5``)
+        """
+        self.required = required
+        self.optional = optional
+
+
+def foo_func(required: str, optional: int = 5):
+    """Foo func.
+
+    Args:
+        required (str): Required parameter.
+        optional (int, optional): Optional parameter. (default: ``5``)
+    """
+    del required, optional  # unused
+
+
+def missing_foo_docstring(foo: str):
+    """Foo func."""
+    del foo  # unused
+
+
+def missing_docstring(foo: str):
+    del foo  # unused
+
+
+def malformed_docstring(foo: str):
+    """Docstring
+
+    Args:
+        foo (Leaving parenthesis open...
+    """
+
+
+@pytest.fixture
+def mock_required_field(monkeypatch: pytest.MonkeyPatch):
+    mock = Mock()
+    mock.return_value = 'MOCK_RETURN'
+    monkeypatch.setattr(yahp.field, 'required', mock)
+    return mock
+
+
+@pytest.fixture
+def mock_optional_field(monkeypatch: pytest.MonkeyPatch):
+    mock = Mock()
+    mock.return_value = 'MOCK_RETURN'
+    monkeypatch.setattr(yahp.field, 'optional', mock)
+    return mock
+
+
+@pytest.mark.parametrize('constructor', [FooClassDocstring, FooClassAndInitDocstring, foo_func])
+class TestHpAuto:
+
+    def test_required(self, constructor: Callable, mock_required_field: Mock):
+        field = hp.auto(constructor, 'required')
+        mock_required_field.assert_called_once_with('Required parameter.')
+        assert field == mock_required_field.return_value
+
+    def test_optional(self, constructor: Callable, mock_optional_field: Mock):
+        field = hp.auto(constructor, 'optional')
+        mock_optional_field.assert_called_once_with('Optional parameter. (default: ``5``)', default=5)
+        assert field == mock_optional_field.return_value
+
+    def test_docstring_override(self, constructor: Callable, mock_optional_field: Mock):
+        field = hp.auto(constructor, 'optional', doc='Custom docstring')
+        mock_optional_field.assert_called_once_with('Custom docstring', default=5)
+        assert field == mock_optional_field.return_value
+
+
+@pytest.mark.parametrize('constructor', [missing_foo_docstring, missing_docstring, malformed_docstring])
+def test_bad_docstring_ignore_errors(constructor: Callable, mock_required_field: Mock):
+    with pytest.warns(match='Argument foo will be undocumented'):
+        field = hp.auto(constructor, 'foo', ignore_docstring_errors=True)
+    mock_required_field.assert_called_once_with('foo')
+    assert field == mock_required_field.return_value
+
+
+@pytest.mark.parametrize('constructor', [missing_foo_docstring, missing_docstring, malformed_docstring])
+def test_bad_docstring_raise_exceptions(constructor: Callable):
+    with pytest.raises((docstring_parser.ParseError, ValueError)):
+        hp.auto(constructor, 'foo')