Type Hints Support for The Sphinx Autodoc Extension

sphinx-autodoc-typehints

This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return f"{value} {unit}"

to this:

from typing import Union


def format_unit(value: Union[float, int], unit: str) -> str:
    """
    Formats the given value as a human readable string using the given units.

    :param value: a numeric value
    :param unit: the unit for the value (kg, m, etc.)
    """
    return f"{value} {unit}"

Installation and setup

First, use pip to download and install the extension:

$ pip install sphinx-autodoc-typehints

Then, add the extension to your conf.py:

extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]

Options

The following configuration options are accepted:

typehints_fully_qualified (default: False): if True, class names are always fully qualified (e.g. module.for.Class). If False, just the class name displays (e.g. Class)

always_document_param_types (default: False): If False, do not add type info for undocumented parameters. If True, add stub documentation for undocumented parameters to be able to add type info.

typehints_document_rtype (default: True): If False, never add an :rtype: directive. If True, add the :rtype: directive if no existing :rtype: is found.

typehints_use_rtype (default: True): Controls behavior when typehints_document_rtype is set to True. If True, document return type in the :rtype: directive. If False, document return type as part of the :return: directive, if present, otherwise fall back to using :rtype:. Use in conjunction with napoleon_use_rtype to avoid generation of duplicate or redundant return type information.

typehints_defaults (default: None): If None, defaults are not added. Otherwise adds a default annotation:

• 'comma' adds it after the type, changing Sphinx’ default look to “param (int, default: 1) -- text”.
• 'braces' adds (default: ...) after the type (useful for numpydoc like styles).
• 'braces-after' adds (default: ...) at the end of the parameter documentation text instead.

simplify_optional_unions (default: True): If True, optional parameters of type "Union[...]" are simplified as being of type Union[..., None] in the resulting documention (e.g. Optional[Union[A, B]] -> Union[A, B, None]). If False, the "Optional"-type is kept. Note: If False, any Union containing None will be displayed as Optional! Note: If an optional parameter has only a single type (e.g Optional[A] or Union[A, None]), it will always be displayed as Optional!

typehints_formatter (default: None): If set to a function, this function will be called with annotation as first argument and sphinx.config.Config argument second. The function is expected to return a string with reStructuredText code or None to fall back to the default formatter.

How it works

The extension listens to the autodoc-process-signature and autodoc-process-docstring Sphinx events. In the former, it strips the annotations from the function signature. In the latter, it injects the appropriate :type argname: and :rtype: directives into the docstring.

Only arguments that have an existing :param: directive in the docstring get their respective :type: directives added. The :rtype: directive is added if and only if no existing :rtype: is found.

Compatibility with sphinx.ext.napoleon

To use sphinx.ext.napoleon with sphinx-autodoc-typehints, make sure you load sphinx.ext.napoleon first, before sphinx-autodoc-typehints. See Issue 15 on the issue tracker for more information.

Dealing with circular imports

Sometimes functions or classes from two different modules need to reference each other in their type annotations. This creates a circular import problem. The solution to this is the following:

1. Import only the module, not the classes/functions from it
2. Use forward references in the type annotations (e.g. def methodname(self, param1: 'othermodule.OtherClass'):)

On Python 3.7, you can even use from __future__ import annotations and remove the quotes.

Using type hint comments

If you're documenting code that needs to stay compatible with Python 2.7, you cannot use regular type annotations. Instead, you must either be using Python 3.8 or later or have typed_ast installed. The package extras type_comments will pull in the appropiate dependencies automatically. Then you can add type hint comments in the following manner:

def myfunction(arg1, arg2):
    # type: (int, str) -> int
    return 42

or alternatively:

def myfunction(
    arg1,  # type: int
    arg2,  # type: str
):
    # type: (...) -> int
    return 42

Author: Tox-dev
Source Code: https://github.com/tox-dev/sphinx-autodoc-typehints 
License: View license

#python #sphinx 

What is GEEK

Buddha Community

Type Hints Support for The Sphinx Autodoc Extension

sphinx-autodoc-typehints

This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return f"{value} {unit}"

to this:

from typing import Union


def format_unit(value: Union[float, int], unit: str) -> str:
    """
    Formats the given value as a human readable string using the given units.

    :param value: a numeric value
    :param unit: the unit for the value (kg, m, etc.)
    """
    return f"{value} {unit}"

Installation and setup

First, use pip to download and install the extension:

$ pip install sphinx-autodoc-typehints

Then, add the extension to your conf.py:

extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]

Options

The following configuration options are accepted:

typehints_fully_qualified (default: False): if True, class names are always fully qualified (e.g. module.for.Class). If False, just the class name displays (e.g. Class)

always_document_param_types (default: False): If False, do not add type info for undocumented parameters. If True, add stub documentation for undocumented parameters to be able to add type info.

typehints_document_rtype (default: True): If False, never add an :rtype: directive. If True, add the :rtype: directive if no existing :rtype: is found.

typehints_use_rtype (default: True): Controls behavior when typehints_document_rtype is set to True. If True, document return type in the :rtype: directive. If False, document return type as part of the :return: directive, if present, otherwise fall back to using :rtype:. Use in conjunction with napoleon_use_rtype to avoid generation of duplicate or redundant return type information.

typehints_defaults (default: None): If None, defaults are not added. Otherwise adds a default annotation:

• 'comma' adds it after the type, changing Sphinx’ default look to “param (int, default: 1) -- text”.
• 'braces' adds (default: ...) after the type (useful for numpydoc like styles).
• 'braces-after' adds (default: ...) at the end of the parameter documentation text instead.

simplify_optional_unions (default: True): If True, optional parameters of type "Union[...]" are simplified as being of type Union[..., None] in the resulting documention (e.g. Optional[Union[A, B]] -> Union[A, B, None]). If False, the "Optional"-type is kept. Note: If False, any Union containing None will be displayed as Optional! Note: If an optional parameter has only a single type (e.g Optional[A] or Union[A, None]), it will always be displayed as Optional!

typehints_formatter (default: None): If set to a function, this function will be called with annotation as first argument and sphinx.config.Config argument second. The function is expected to return a string with reStructuredText code or None to fall back to the default formatter.

How it works

The extension listens to the autodoc-process-signature and autodoc-process-docstring Sphinx events. In the former, it strips the annotations from the function signature. In the latter, it injects the appropriate :type argname: and :rtype: directives into the docstring.

Only arguments that have an existing :param: directive in the docstring get their respective :type: directives added. The :rtype: directive is added if and only if no existing :rtype: is found.

Compatibility with sphinx.ext.napoleon

To use sphinx.ext.napoleon with sphinx-autodoc-typehints, make sure you load sphinx.ext.napoleon first, before sphinx-autodoc-typehints. See Issue 15 on the issue tracker for more information.

Dealing with circular imports

Sometimes functions or classes from two different modules need to reference each other in their type annotations. This creates a circular import problem. The solution to this is the following:

1. Import only the module, not the classes/functions from it
2. Use forward references in the type annotations (e.g. def methodname(self, param1: 'othermodule.OtherClass'):)

On Python 3.7, you can even use from __future__ import annotations and remove the quotes.

Using type hint comments

If you're documenting code that needs to stay compatible with Python 2.7, you cannot use regular type annotations. Instead, you must either be using Python 3.8 or later or have typed_ast installed. The package extras type_comments will pull in the appropiate dependencies automatically. Then you can add type hint comments in the following manner:

def myfunction(arg1, arg2):
    # type: (int, str) -> int
    return 42

or alternatively:

def myfunction(
    arg1,  # type: int
    arg2,  # type: str
):
    # type: (...) -> int
    return 42

Author: Tox-dev
Source Code: https://github.com/tox-dev/sphinx-autodoc-typehints 
License: View license

#python #sphinx 

Some Helpful Extensions When Dealing With Types in .NET

If you are writing reusable code, chances are high that you will write quite some code that deals with types, generics, and interfaces. Over the years, the collection of my helper extensions for that have grown. As some of my upcoming posts use them, I share them (also) for future reference.

1. Check if a Type Is Deriving From Another Type

Deriving types is a common practice. To some extent, you can use pattern matching. Sometimes, that isn’t enough, though (especially if you have a multi-level derivation path). This is when I use one of these two extensions:

Java

1

        public static bool IsDerivingFrom(this Type type, Type searchType)

2

        {

3

            if (type == null) throw new NullReferenceException();

4

5

            return

6

                type.BaseType != null &&

7

                (type.BaseType == searchType ||

8

                type.BaseType.IsDerivingFrom(searchType));

9

        }

10

11

        public static bool IsDerivingFromGenericType(this Type type, Type searchGenericType)

12

        {

13

            if (type == null) throw new ArgumentNullException(nameof(type));

14

            if (searchGenericType == null) throw new ArgumentNullException(nameof(searchGenericType));

15

16

            return

17

                type != typeof(object) &&

18

                (type.IsGenericType &&

19

                searchGenericType.GetGenericTypeDefinition() == searchGenericType ||

20

                IsDerivingFromGenericType(type.BaseType, searchGenericType));

21

        }

Update 1: Type.IsSubclassOf will give you the same result as IsDerivingFrom. The main purpose was (is) to use my implementation when having multiple levels of derivation and being able to debug the whole detection process.

2. Get Type of T From IEnumerable

Sometimes, one needs to know the item type of an IEnumerable. These two extensions will help you in this case:

Java

1

        [System.Diagnostics.CodeAnalysis.SuppressMessage("Style", "IDE0060:Remove unused parameter", Justification = "Extension method")]

2

        public static Type GetItemType<T>(this IEnumerable<T> enumerable) => typeof(T);

3

4

        public static Type? GetItemType(this object enumerable)

5

            => enumerable == null ? null :

6

            (enumerable.GetType().GetInterface(typeof(IEnumerable<>).Name)?.GetGenericArguments()[0]);

3. Check if a Type Implements a Certain Interface

Interfaces are supposed to make the life of a developer easier. Like with the type derivation, sometimes we need to know if a type implements a certain interface. This extension answers the question for you:

Java

1

        public static bool ImplementsInterface(this Type? type, Type? @interface)

2

        {

3

            bool result = false;

4

5

            if (type == null || @interface == null)

6

                return result;

7

8

            var interfaces = type.GetInterfaces();

9

            if (@interface.IsGenericTypeDefinition)

10

            {

11

                foreach (var item in interfaces)

12

                {

13

                    if (item.IsConstructedGenericType && item.GetGenericTypeDefinition() == @interface)

14

                        result = true;

15

                }

16

            }

17

            else

18

            {

19

                foreach (var item in interfaces)

20

                {

21

                    if (item == @interface)

22

                        result = true;

23

                }

24

            }

25

26

            return result;

27

        }

Update 2: Type.IsAssignableFrom will also tell you if a type implements an interface. As for the IsDerivingFrom method, I wanted to be able to debug the detection, which is - besides from having an explicit implementation - the main reason for this method.

#web dev #mvvm #interface #types #type #assembly #extension methods #dev stories #helper #msicc

Maintain your Magento web app for better Performance

Magento is the best cross-platform framework that helps you to develop the best eCommerce web apps. It is important to maintain your Magento eCommerce web app to increase the performance of your web application.

Magento maintenance and support services play a vital role in maintaining the website because if the website or web app is not maintained properly it can create bugs in the future and many more problems can occur through which there is a chance that customers get frustrated and won’t visit your website again.

Nevina Infotech is the best choice for Magento maintenance and service of your web apps. We have a hardworking team of developers that will help you to increase the performance of your web apps.

#magento maintenance and support services #magento support services #magento support and maintenance #magento support #magento maintenance support #magento technical support

Maintain your Magento app for a smoother and faster user Experience

Magento is the best open-source eCommerce platform for website development. We all know the importance of a website in every sector; whether it is about business or anything else, it can represent the look and feel of your company. So to maintain these websites, it is essential to do Magento support and maintenance so that you can also maintain your website.

Nevina Infotech is the best Magento app development company that can guide you to maintain and support your Magento app. We have a dedicated team of developers who will help you with the maintenance and support of your app.

#magento maintenance and support services #magento support services #magento support and maintenance #magento support #magento maintenance support #magento technical support

Get the best Magento maintenance service for your e-commerce store

Magento is the most demanded technology for developing online eCommerce stores and Magento service is important for better working of the online store. Nevina Infotech provides you with Magento maintenance and services.

Magento maintenance is the process of checking the performance of the website and checking the regular updates, backups, online store management, and much more.

You can choose Nevina Infotech for Magento maintenance service for your eCommerce store. We provide the best Magento support and maintenance for eCommerce stores.

#magento maintenance and support services #magento support services #magento support and maintenance #magento support #magento maintenance support #magento technical support