jcloud-docsgen/tests/unit/cli/test_python.py

# Copyright 2026 jCloud

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import pathlib
import tempfile

import pytest

from jcloud_docsgen.cli.cli import create_argument_parser
from jcloud_docsgen.cli.cli import main as cli_main
from jcloud_docsgen.cli.languages.python import parse_sections_list
from jcloud_docsgen.core.python import (
    PythonDefinitionDocumentationIncludeSections,
)


@pytest.mark.parametrize(
    'include,exclude,expected',
    [
        (
            [],
            [],
            PythonDefinitionDocumentationIncludeSections(
                signature=False,
                returns=False,
                params=False,
                exceptions=False,
                examples=False,
                docstring=False,
                bases=False,
                decorators=False,
                class_body=False,
            ),
        ),
        (
            [],
            ['signature'],
            PythonDefinitionDocumentationIncludeSections(
                signature=False,
                returns=False,
                params=False,
                exceptions=False,
                examples=False,
                docstring=False,
                bases=False,
                decorators=False,
                class_body=False,
            ),
        ),
        (
            ['signature'],
            ['signature'],
            PythonDefinitionDocumentationIncludeSections(
                signature=False,
                returns=False,
                params=False,
                exceptions=False,
                examples=False,
                docstring=False,
                bases=False,
                decorators=False,
                class_body=False,
            ),
        ),
        (
            ['signature'],
            [],
            PythonDefinitionDocumentationIncludeSections(
                signature=True,
                returns=False,
                params=False,
                exceptions=False,
                examples=False,
                docstring=False,
                bases=False,
                decorators=False,
                class_body=False,
            ),
        ),
        (
            None,
            [],
            PythonDefinitionDocumentationIncludeSections(),
        ),
        (
            ['signature', 'exceptions', 'bases', 'class_body'],
            ['signature', 'bases'],
            PythonDefinitionDocumentationIncludeSections(
                signature=False,
                returns=False,
                params=False,
                exceptions=True,
                examples=False,
                docstring=False,
                bases=False,
                decorators=False,
                class_body=True,
            ),
        ),
        (
            None,
            ['params', 'docstring'],
            PythonDefinitionDocumentationIncludeSections(
                signature=True,
                returns=True,
                params=False,
                exceptions=True,
                examples=True,
                docstring=False,
                bases=True,
                decorators=True,
                class_body=True,
            ),
        ),
    ],
)
def test_parse_sections_list(include, exclude, expected):
    assert parse_sections_list(include, exclude) == expected


def test_sections_error():
    parser = create_argument_parser()

    with pytest.raises(SystemExit):
        parser.parse_args(
            [
                'python',
                '-s',
                'param',  # correct: `params`
            ]
        )

    with pytest.raises(SystemExit):
        parser.parse_args(
            [
                'python',
                '-s',
                'params',
                'docstrng',  # correct: `docstring`
            ]
        )


def test_sections_success():
    parser = create_argument_parser()

    parser.parse_args(
        [
            'python',
            '-s',
            'params',
        ]
    )
    parser.parse_args(
        [
            'python',
            '-s',
            'params',
            'docstring',
        ]
    )


def test_docs_generation(expectdir):
    with expectdir('python_project') as output_dir:
        output_dir: pathlib.Path
        (output_dir / 'test_dir').mkdir()
        input_dir = pathlib.Path(__file__).parent / 'python_project/project'
        assert (
            cli_main(
                [
                    'python',
                    '-s',
                    'params',
                    'docstring',
                    '-HTfo',
                    str(output_dir),
                    str(input_dir),
                ]
            )
            == 0
        )


def test_docs_generation_error():
    with tempfile.TemporaryDirectory() as output_dir:
        output_dir = pathlib.Path(output_dir)
        (output_dir / 'test_dir').mkdir()
        input_dir = pathlib.Path(__file__).parent / 'python_project/project'
        assert (
            cli_main(
                [
                    'python',
                    '-s',
                    'params',
                    'docstring',
                    '-HTo',
                    str(output_dir),
                    str(input_dir),
                ]
            )
            == 1
        )