# This is a good example.
# bad example
# Bad example

def objective(trial):
    ...

def objective(trial: optuna.trial.Trial) -> float:
    ...

class PublicClass:  # This class is exposed to external libraries.
    def __init__(self):
        self.public_field = 10            # This field is supposed to be accessed from other libraries.
        self._package_private_field = 20  # This field is supposed to be accessed only within the same library.
        self._private_field = 30          # This field is supposed to be accessed only within the same class.

    def public_method(self):
        pass

    def _package_private_method(self):
        pass

    def _private_method(self):
        pass


class _PackagePrivateClass:  # This class is supposed to be accessed only within the same library.
    def __init__(self):
        self.package_private_field = 10  # This field can be accessed from any place within the same library.
        self._private_field = 20         # This field is supposed to be accessed only within the same class.

    def package_private_method(self):
        pass

    def _private_method(self):
        pass


class _PrivateClass:  # This class is supposed to be accessed only within the same module.
    def __init__(self):
        self.package_private_field = 10  # This field can be accessed from any place within the same module.
        self._private_field = 20         # This field is supposed to be accessed only within the same class.

    def package_private_method(self):
        pass

    def _private_method(self):
        pass


def _package_private_function():  # This function is supposed to be accessed only within the same library.
    pass


def _private_function():  # This function is supposed to be accessed only within the same module.
    pass

def test_foo():
    ...
    assert actual == expected

def TestFoo(unittest.Testcase):
    def test_foo(self):
        ...
        self.assertEqual(actual, expected)

def example_function(param1: int, param2: str) -> bool:
    """An example of function docstrings.
    
    Example:
        Using `testsetup` and `testcode`.

        .. testsetup::
            import numpy as np
                
        .. testcode::
            x = np.zeros(10)

    Args:
        param1:
            The first parameter.
        param2:
            The second parameter.

    Returns:
        The return value. :obj:`True` for success, :obj:`False` otherwise.

    """
    return True

class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    If the class has public attributes, they may be documented here
    in an ``Attributes`` section and follow the same formatting as a
    function's ``Args`` section.

    Properties created with the ``@property`` decorator should be documented
    in the property's getter method.

    The `__init__` method must be documented in the class level docstring,
    not as a docstring on the `__init__` method.

    Args:
        param1:
            Description of `param1`.
        param2:
            Description of `param2`. Multiple
            lines are supported.

    Attributes:
        attr1:
            Description of `attr1`.
        attr2:
            Description of `attr2`.

    """

    def __init__(self, param1: str, param2: Optional[int] = 0):
        self.attr1 = param1
        self.attr2 = param2

    @property
    def readonly_property(self) -> str:
        """Properties should be documented in their getter method."""
        return "readonly_property"

    @property
    def readwrite_property(self) -> List[str]:
        """Properties with both a getter and setter
        should only be documented in their getter method.

        If the setter method contains notable behavior, it should be
        mentioned here.
        """
        return ["readwrite_property"]

    @readwrite_property.setter
    def readwrite_property(self, value: int) -> int:
        value

    def example_method(self, param1: str, param2: int) -> bool:
        """Class methods are similar to regular functions.

        Example:
            Using `testsetup` and `testcode`.

            .. testsetup::
                import numpy as np
                
            .. testcode::
                x = np.zeros(10)

        Note:
            Do not include the `self` parameter in the ``Args`` section.
            (Instead of ``Note:``, you can use ``.. note::``.)

        Args:
            param1:
                The first parameter.
            param2:
                The second parameter.

        Returns:
            :obj:`True` if successful, :obj:`False` otherwise.

        """
        return True

def some_function(x: float):
   """...

   ...

   Args:
       x:
           Positive real number.

   """

def some_function(x: float):
   """...

   ...

   Args:
       x:
           Positive real number.

   Raises:
       :exc:`ValueError`:
           ``x`` is negative.

   """

from optuna._experimental import experimental

# Function: https://github.com/optuna/optuna/blob/248892e2/optuna/integration/lightgbm_tuner/__init__.py
@experimental("0.18.0")
def train(*args: Any, **kwargs: Any) -> Any:
    ...

# Class: https://github.com/optuna/optuna/blob/8d9576d7/optuna/pruners/hyperband.py
@experimental("1.1.0")
class HyperbandPruner(BasePruner):
    ...

# Method: https://github.com/optuna/optuna/blob/6e31e242/optuna/progress_bar.py
class _ProgressBar(object):
    ...

    @experimental("1.2.0", name="Progress bar")
    def _init_valid(self) -> None:
        ...

import warnings

from optuna import logging

# Deprecate a feature which we cannot use the deprecation decorator, then use `warnings.warn()`
# https://github.com/optuna/optuna/blob/4d6e1c7e5f163744136dd1b67593d03cb977bc0f/optuna/cli.py
class _StudyOptimize(_BaseCommand):
    ...
    def take_action(self, parsed_args):
        # type: (Namespace) -> int

        message = (
            "The use of the `study optimize` command is deprecated. Please execute your Python "
            "script directly instead."
        )
        warnings.warn(message, DeprecationWarning)
        ...

# Warn the exceptional sampler is used for the `CmaEsSampler` due to out of bounds, then use `optuna.logging.Logger.warnings()`.
# https://github.com/optuna/optuna/blob/4d6e1c7e5f163744136dd1b67593d03cb977bc0f/optuna/samplers/_cmaes.py
_logger = logging.get_logger(__name__)


class CmaEsSampler(BaseSampler):
    ...
     def _log_independent_sampling(self, trial: FrozenTrial, param_name: str) -> None:
        self._logger.warning(
            "The parameter '{}' in trial#{} is sampled independently "
            "by using `{}` instead of `CmaEsSampler` "
            "(optimization performance may be degraded). "
            "You can suppress this warning by setting `warn_independent_sampling` "
            "to `False` in the constructor of `CmaEsSampler`, "
            "if this independent sampling is intended behavior.".format(
                param_name, trial.number, self._independent_sampler.__class__.__name__
            )
        )
    ...

def objective(trial: Trial) -> float:
    x = trial.suggest_float("x", 0, 1)
    y = trial.suggest_float("y", 1e-7, 1e-2, log=True)
    z = trial.suggest_float("z", 0, 10, step=0.5)
    ...

def objective(trial: Trial) -> float:
    x = trial.suggest_uniform("x", 0, 1)
    y = trial.suggest_loguniform("y", 1e-7, 1e-2)
    z = trial.suggest_discrete_uniform("z", 0, 10, q=0.5)
    ...