class django.views.generic.list.BaseListView
A base view for displaying a list of objects. It is not intended to be used directly, but rather as a parent class of the django.views.generic.list.ListView or other views representing lists of objects. Ancestors (MRO) This view inherits methods and attributes from the following views:  django.views.generic.list.MultipleObjectMixin django.views.generic.base.View  Methods
get(request, *args, **kwargs)
Adds object_list to the context. If allow_empty is True then display an empty list. If allow_empty is False then raise a 404 error.


get(request, *args, **kwargs)
Adds object_list to the context. If allow_empty is True then display an empty list. If allow_empty is False then raise a 404 error.


class django.views.generic.list.ListView
A page representing a list of objects. While this view is executing, self.object_list will contain the list of objects (usually, but not necessarily a queryset) that the view is operating upon. Ancestors (MRO) This view inherits methods and attributes from the following views:  django.views.generic.list.MultipleObjectTemplateResponseMixin django.views.generic.base.TemplateResponseMixin django.views.generic.list.BaseListView django.views.generic.list.MultipleObjectMixin django.views.generic.base.View  Method Flowchart  setup() dispatch() http_method_not_allowed() get_template_names() get_queryset() get_context_object_name() get_context_data() get() render_to_response()  Example views.py: from django.utils import timezone
from django.views.generic.list import ListView

from articles.models import Article

class ArticleListView(ListView):

    model = Article
    paginate_by = 100  # if pagination is desired

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['now'] = timezone.now()
        return context
 Example myapp/urls.py: from django.urls import path

from article.views import ArticleListView

urlpatterns = [
    path('', ArticleListView.as_view(), name='article-list'),
]
 Example myapp/article_list.html:
Articles

{% for article in object_list %}

{{ article.pub_date|date }} - {{ article.headline }}

{% empty %}

No articles yet.

{% endfor %}

 If you’re using pagination, you can adapt the example template from the pagination docs. Change instances of contacts in that example template to page_obj.


class django.views.generic.list.MultipleObjectMixin
A mixin that can be used to display a list of objects. If paginate_by is specified, Django will paginate the results returned by this. You can specify the page number in the URL in one of two ways:
Use the page parameter in the URLconf. For example, this is what your URLconf might look like: path('objects/page<int:page>/', PaginatedView.as_view()),

Pass the page number via the page query-string parameter. For example, a URL would look like this: /objects/?page=3
   These values and lists are 1-based, not 0-based, so the first page would be represented as page 1. For more on pagination, read the pagination documentation. As a special case, you are also permitted to use last as a value for page: /objects/?page=last
 This allows you to access the final page of results without first having to determine how many pages there are. Note that page must be either a valid page number or the value last; any other value for page will result in a 404 error. Extends  django.views.generic.base.ContextMixin  Methods and Attributes
allow_empty
A boolean specifying whether to display the page if no objects are available. If this is False and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is True.

model
The model that this view will display data for. Specifying model
= Foo is effectively the same as specifying queryset =
Foo.objects.all(), where objects stands for Foo’s default manager.

queryset
A QuerySet that represents the objects. If provided, the value of queryset supersedes the value provided for model.  Warning queryset is a class attribute with a mutable value so care must be taken when using it directly. Before using it, either call its all() method or retrieve it with get_queryset() which takes care of the cloning behind the scenes.

ordering
A string or list of strings specifying the ordering to apply to the queryset. Valid values are the same as those for order_by().

paginate_by
An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with paginate_by objects per page. The view will expect either a page query string parameter (via request.GET) or a page variable specified in the URLconf.

paginate_orphans
An integer specifying the number of “overflow” objects the last page can contain. This extends the paginate_by limit on the last page by up to paginate_orphans, in order to keep the last page from having a very small number of objects.

page_kwarg
A string specifying the name to use for the page parameter. The view will expect this parameter to be available either as a query string parameter (via request.GET) or as a kwarg variable specified in the URLconf. Defaults to page.

paginator_class
The paginator class to be used for pagination. By default, django.core.paginator.Paginator is used. If the custom paginator class doesn’t have the same constructor interface as django.core.paginator.Paginator, you will also need to provide an implementation for get_paginator().

context_object_name
Designates the name of the variable to use in the context.

get_queryset()
Get the list of items for this view. This must be an iterable and may be a queryset (in which queryset-specific behavior will be enabled).

get_ordering()
Returns a string (or iterable of strings) that defines the ordering that will be applied to the queryset. Returns ordering by default.

paginate_queryset(queryset, page_size)
Returns a 4-tuple containing (paginator, page, object_list, is_paginated). Constructed by paginating queryset into pages of size page_size. If the request contains a page argument, either as a captured URL argument or as a GET argument, object_list will correspond to the objects from that page.

get_paginate_by(queryset)
Returns the number of items to paginate by, or None for no pagination. By default this returns the value of paginate_by.

get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
Returns an instance of the paginator to use for this view. By default, instantiates an instance of paginator_class.

get_paginate_orphans()
An integer specifying the number of “overflow” objects the last page can contain. By default this returns the value of paginate_orphans.

get_allow_empty()
Return a boolean specifying whether to display the page if no objects are available. If this method returns False and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is True.

get_context_object_name(object_list)
Return the context variable name that will be used to contain the list of data that this view is manipulating. If object_list is a queryset of Django objects and context_object_name is not set, the context name will be the model_name of the model that the queryset is composed from, with postfix '_list' appended. For example, the model Article would have a context object named article_list.

get_context_data(**kwargs)
Returns context data for displaying the list of objects.
 Context
object_list: The list of objects that this view is displaying. If context_object_name is specified, that variable will also be set in the context, with the same value as object_list.
is_paginated: A boolean representing whether the results are paginated. Specifically, this is set to False if no page size has been specified, or if the available objects do not span multiple pages.
paginator: An instance of django.core.paginator.Paginator. If the page is not paginated, this context variable will be None.
page_obj: An instance of django.core.paginator.Page. If the page is not paginated, this context variable will be None.


allow_empty
A boolean specifying whether to display the page if no objects are available. If this is False and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is True.


context_object_name
Designates the name of the variable to use in the context.


get_allow_empty()
Return a boolean specifying whether to display the page if no objects are available. If this method returns False and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is True.


get_context_data(**kwargs)
Returns context data for displaying the list of objects.


get_context_object_name(object_list)
Return the context variable name that will be used to contain the list of data that this view is manipulating. If object_list is a queryset of Django objects and context_object_name is not set, the context name will be the model_name of the model that the queryset is composed from, with postfix '_list' appended. For example, the model Article would have a context object named article_list.


get_ordering()
Returns a string (or iterable of strings) that defines the ordering that will be applied to the queryset. Returns ordering by default.


get_paginate_by(queryset)
Returns the number of items to paginate by, or None for no pagination. By default this returns the value of paginate_by.


get_paginate_orphans()
An integer specifying the number of “overflow” objects the last page can contain. By default this returns the value of paginate_orphans.


get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
Returns an instance of the paginator to use for this view. By default, instantiates an instance of paginator_class.


get_queryset()
Get the list of items for this view. This must be an iterable and may be a queryset (in which queryset-specific behavior will be enabled).


model
The model that this view will display data for. Specifying model
= Foo is effectively the same as specifying queryset =
Foo.objects.all(), where objects stands for Foo’s default manager.


ordering
A string or list of strings specifying the ordering to apply to the queryset. Valid values are the same as those for order_by().


page_kwarg
A string specifying the name to use for the page parameter. The view will expect this parameter to be available either as a query string parameter (via request.GET) or as a kwarg variable specified in the URLconf. Defaults to page.


paginate_by
An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with paginate_by objects per page. The view will expect either a page query string parameter (via request.GET) or a page variable specified in the URLconf.


paginate_orphans
An integer specifying the number of “overflow” objects the last page can contain. This extends the paginate_by limit on the last page by up to paginate_orphans, in order to keep the last page from having a very small number of objects.


paginate_queryset(queryset, page_size)
Returns a 4-tuple containing (paginator, page, object_list, is_paginated). Constructed by paginating queryset into pages of size page_size. If the request contains a page argument, either as a captured URL argument or as a GET argument, object_list will correspond to the objects from that page.


paginator_class
The paginator class to be used for pagination. By default, django.core.paginator.Paginator is used. If the custom paginator class doesn’t have the same constructor interface as django.core.paginator.Paginator, you will also need to provide an implementation for get_paginator().


queryset
A QuerySet that represents the objects. If provided, the value of queryset supersedes the value provided for model.  Warning queryset is a class attribute with a mutable value so care must be taken when using it directly. Before using it, either call its all() method or retrieve it with get_queryset() which takes care of the cloning behind the scenes.


class django.views.generic.list.MultipleObjectTemplateResponseMixin
A mixin class that performs template-based response rendering for views that operate upon a list of object instances. Requires that the view it is mixed with provides self.object_list, the list of object instances that the view is operating on. self.object_list may be, but is not required to be, a QuerySet. Extends  TemplateResponseMixin  Methods and Attributes
template_name_suffix
The suffix to append to the auto-generated candidate template name. Default suffix is _list.

get_template_names()
Returns a list of candidate template names. Returns the following list:  the value of template_name on the view (if provided) <app_label>/<model_name><template_name_suffix>.html


get_template_names()
Returns a list of candidate template names. Returns the following list:  the value of template_name on the view (if provided) <app_label>/<model_name><template_name_suffix>.html


template_name_suffix
The suffix to append to the auto-generated candidate template name. Default suffix is _list.


class JavaScriptCatalog
A view that produces a JavaScript code library with functions that mimic the gettext interface, plus an array of translation strings. Attributes
domain
Translation domain containing strings to add in the view output. Defaults to 'djangojs'.

packages
A list of application names among installed applications. Those apps should contain a locale directory. All those catalogs plus all catalogs found in LOCALE_PATHS (which are always included) are merged into one catalog. Defaults to None, which means that all available translations from all INSTALLED_APPS are provided in the JavaScript output.
 Example with default values: from django.views.i18n import JavaScriptCatalog

urlpatterns = [
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
]
 Example with custom packages: urlpatterns = [
    path('jsi18n/myapp/',
         JavaScriptCatalog.as_view(packages=['your.app.label']),
         name='javascript-catalog'),
]
 If your root URLconf uses i18n_patterns(), JavaScriptCatalog must also be wrapped by i18n_patterns() for the catalog to be correctly generated. Example with i18n_patterns(): from django.conf.urls.i18n import i18n_patterns

urlpatterns = i18n_patterns(
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
)


domain
Translation domain containing strings to add in the view output. Defaults to 'djangojs'.


packages
A list of application names among installed applications. Those apps should contain a locale directory. All those catalogs plus all catalogs found in LOCALE_PATHS (which are always included) are merged into one catalog. Defaults to None, which means that all available translations from all INSTALLED_APPS are provided in the JavaScript output.


class JSONCatalog
In order to use another client-side library to handle translations, you may want to take advantage of the JSONCatalog view. It’s similar to JavaScriptCatalog but returns a JSON response. See the documentation for JavaScriptCatalog to learn about possible values and use of the domain and packages attributes. The response format is as follows: {
    "catalog": {
        # Translations catalog
    },
    "formats": {
        # Language formats for date, time, etc.
    },
    "plural": "..."  # Expression for plural forms, or null.
}


static.serve(request, path, document_root, show_indexes=False)


Widgets A widget is Django’s representation of an HTML input element. The widget handles the rendering of the HTML, and the extraction of data from a GET/POST dictionary that corresponds to the widget. The HTML generated by the built-in widgets uses HTML5 syntax, targeting <!DOCTYPE html>. For example, it uses boolean attributes such as checked rather than the XHTML style of checked='checked'.  Tip Widgets should not be confused with the form fields. Form fields deal with the logic of input validation and are used directly in templates. Widgets deal with rendering of HTML form input elements on the web page and extraction of raw submitted data. However, widgets do need to be assigned to form fields.  Specifying widgets Whenever you specify a field on a form, Django will use a default widget that is appropriate to the type of data that is to be displayed. To find which widget is used on which field, see the documentation about Built-in Field classes. However, if you want to use a different widget for a field, you can use the widget argument on the field definition. For example: from django import forms

class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField(widget=forms.Textarea)
 This would specify a form with a comment that uses a larger Textarea widget, rather than the default TextInput widget. Setting arguments for widgets Many widgets have optional extra arguments; they can be set when defining the widget on the field. In the following example, the years attribute is set for a SelectDateWidget: from django import forms

BIRTH_YEAR_CHOICES = ['1980', '1981', '1982']
FAVORITE_COLORS_CHOICES = [
    ('blue', 'Blue'),
    ('green', 'Green'),
    ('black', 'Black'),
]

class SimpleForm(forms.Form):
    birth_year = forms.DateField(widget=forms.SelectDateWidget(years=BIRTH_YEAR_CHOICES))
    favorite_colors = forms.MultipleChoiceField(
        required=False,
        widget=forms.CheckboxSelectMultiple,
        choices=FAVORITE_COLORS_CHOICES,
    )
 See the Built-in widgets for more information about which widgets are available and which arguments they accept. Widgets inheriting from the Select widget Widgets inheriting from the Select widget deal with choices. They present the user with a list of options to choose from. The different widgets present this choice differently; the Select widget itself uses a <select> HTML list representation, while RadioSelect uses radio buttons. Select widgets are used by default on ChoiceField fields. The choices displayed on the widget are inherited from the ChoiceField and changing ChoiceField.choices will update Select.choices. For example: >>> from django import forms
>>> CHOICES = [('1', 'First'), ('2', 'Second')]
>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
>>> choice_field.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices = []
>>> choice_field.choices = [('1', 'First and only')]
>>> choice_field.widget.choices
[('1', 'First and only')]
 Widgets which offer a choices attribute can however be used with fields which are not based on choice – such as a CharField – but it is recommended to use a ChoiceField-based field when the choices are inherent to the model and not just the representational widget. Customizing widget instances When Django renders a widget as HTML, it only renders very minimal markup - Django doesn’t add class names, or any other widget-specific attributes. This means, for example, that all TextInput widgets will appear the same on your web pages. There are two ways to customize widgets: per widget instance and per widget class. Styling widget instances If you want to make one widget instance look different from another, you will need to specify additional attributes at the time when the widget object is instantiated and assigned to a form field (and perhaps add some rules to your CSS files). For example, take the following form: from django import forms

class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()
 This form will include three default TextInput widgets, with default rendering – no CSS class, no extra attributes. This means that the input boxes provided for each widget will be rendered exactly the same: >>> f = CommentForm(auto_id=False)
>>> f.as_table()

Name:	<input type="text" name="name" required>

Url:	<input type="url" name="url" required>

Comment:	<input type="text" name="comment" required>

 On a real web page, you probably don’t want every widget to look the same. You might want a larger input element for the comment, and you might want the ‘name’ widget to have some special CSS class. It is also possible to specify the ‘type’ attribute to take advantage of the new HTML5 input types. To do this, you use the Widget.attrs argument when creating the widget: class CommentForm(forms.Form):
    name = forms.CharField(widget=forms.TextInput(attrs={'class': 'special'}))
    url = forms.URLField()
    comment = forms.CharField(widget=forms.TextInput(attrs={'size': '40'}))
 You can also modify a widget in the form definition: class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

    name.widget.attrs.update({'class': 'special'})
    comment.widget.attrs.update(size='40')
 Or if the field isn’t declared directly on the form (such as model form fields), you can use the Form.fields attribute: class CommentForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields['name'].widget.attrs.update({'class': 'special'})
        self.fields['comment'].widget.attrs.update(size='40')
 Django will then include the extra attributes in the rendered output: >>> f = CommentForm(auto_id=False)
>>> f.as_table()

Name:	<input type="text" name="name" class="special" required>

Url:	<input type="url" name="url" required>

Comment:	<input type="text" name="comment" size="40" required>

 You can also set the HTML id using attrs. See BoundField.id_for_label for an example. Styling widget classes With widgets, it is possible to add assets (css and javascript) and more deeply customize their appearance and behavior. In a nutshell, you will need to subclass the widget and either define a “Media” inner class or create a “media” property. These methods involve somewhat advanced Python programming and are described in detail in the Form Assets topic guide. Base widget classes Base widget classes Widget and MultiWidget are subclassed by all the built-in widgets and may serve as a foundation for custom widgets. Widget
class Widget(attrs=None)
This abstract class cannot be rendered, but provides the basic attribute attrs. You may also implement or override the render() method on custom widgets.
attrs
A dictionary containing HTML attributes to be set on the rendered widget. >>> from django import forms
>>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name'})
>>> name.render('name', 'A name')
'<input title="Your name" type="text" name="name" value="A name" size="10">'
 If you assign a value of True or False to an attribute, it will be rendered as an HTML5 boolean attribute: >>> name = forms.TextInput(attrs={'required': True})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name" required>'
>>>
>>> name = forms.TextInput(attrs={'required': False})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name">'

supports_microseconds
An attribute that defaults to True. If set to False, the microseconds part of datetime and time values will be set to 0.

format_value(value)
Cleans and returns a value for use in the widget template. value isn’t guaranteed to be valid input, therefore subclass implementations should program defensively.

get_context(name, value, attrs)
Returns a dictionary of values to use when rendering the widget template. By default, the dictionary contains a single key, 'widget', which is a dictionary representation of the widget containing the following keys:
'name': The name of the field from the name argument.
'is_hidden': A boolean indicating whether or not this widget is hidden.
'required': A boolean indicating whether or not the field for this widget is required.
'value': The value as returned by format_value().
'attrs': HTML attributes to be set on the rendered widget. The combination of the attrs attribute and the attrs argument.
'template_name': The value of self.template_name.  Widget subclasses can provide custom context values by overriding this method.

id_for_label(id_)
Returns the HTML ID attribute of this widget for use by a , given the ID of the field. Returns None if an ID isn’t available. This hook is necessary because some widgets have multiple HTML elements and, thus, multiple IDs. In that case, this method should return an ID value that corresponds to the first ID in the widget’s tags.

render(name, value, attrs=None, renderer=None)
Renders a widget to HTML using the given renderer. If renderer is None, the renderer from the FORM_RENDERER setting is used.

value_from_datadict(data, files, name)
Given a dictionary of data and this widget’s name, returns the value of this widget. files may contain data coming from request.FILES. Returns None if a value wasn’t provided. Note also that value_from_datadict may be called more than once during handling of form data, so if you customize it and add expensive processing, you should implement some caching mechanism yourself.

value_omitted_from_data(data, files, name)
Given data and files dictionaries and this widget’s name, returns whether or not there’s data or files for the widget. The method’s result affects whether or not a field in a model form falls back to its default. Special cases are CheckboxInput, CheckboxSelectMultiple, and SelectMultiple, which always return False because an unchecked checkbox and unselected <select multiple> don’t appear in the data of an HTML form submission, so it’s unknown whether or not the user submitted a value.

use_required_attribute(initial)
Given a form field’s initial value, returns whether or not the widget can be rendered with the required HTML attribute. Forms use this method along with Field.required and Form.use_required_attribute to determine whether or not to display the required attribute for each field. By default, returns False for hidden widgets and True otherwise. Special cases are FileInput and ClearableFileInput, which return False when initial is set, and CheckboxSelectMultiple, which always returns False because browser validation would require all checkboxes to be checked instead of at least one. Override this method in custom widgets that aren’t compatible with browser validation. For example, a WSYSIWG text editor widget backed by a hidden textarea element may want to always return False to avoid browser validation on the hidden field.

 MultiWidget
class MultiWidget(widgets, attrs=None)
A widget that is composed of multiple widgets. MultiWidget works hand in hand with the MultiValueField. MultiWidget has one required argument:
widgets
An iterable containing the widgets needed. For example: >>> from django.forms import MultiWidget, TextInput
>>> widget = MultiWidget(widgets=[TextInput, TextInput])
>>> widget.render('name', ['john', 'paul'])
'<input type="text" name="name_0" value="john"><input type="text" name="name_1" value="paul">'
 You may provide a dictionary in order to specify custom suffixes for the name attribute on each subwidget. In this case, for each (key, widget) pair, the key will be appended to the name of the widget in order to generate the attribute value. You may provide the empty string ('') for a single key, in order to suppress the suffix for one widget. For example: >>> widget = MultiWidget(widgets={'': TextInput, 'last': TextInput})
>>> widget.render('name', ['john', 'paul'])
'<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'

 And one required method:
decompress(value)
This method takes a single “compressed” value from the field and returns a list of “decompressed” values. The input value can be assumed valid, but not necessarily non-empty. This method must be implemented by the subclass, and since the value may be empty, the implementation must be defensive. The rationale behind “decompression” is that it is necessary to “split” the combined value of the form field into the values for each widget. An example of this is how SplitDateTimeWidget turns a datetime value into a list with date and time split into two separate values: from django.forms import MultiWidget

class SplitDateTimeWidget(MultiWidget):

    # ...

    def decompress(self, value):
        if value:
            return [value.date(), value.time()]
        return [None, None]
  Tip Note that MultiValueField has a complementary method compress() with the opposite responsibility - to combine cleaned values of all member fields into one.
 It provides some custom context:
get_context(name, value, attrs)
In addition to the 'widget' key described in Widget.get_context(), MultiWidget adds a widget['subwidgets'] key. These can be looped over in the widget template: {% for subwidget in widget.subwidgets %}
    {% include subwidget.template_name with widget=subwidget %}
{% endfor %}

 Here’s an example widget which subclasses MultiWidget to display a date with the day, month, and year in different select boxes. This widget is intended to be used with a DateField rather than a MultiValueField, thus we have implemented value_from_datadict(): from datetime import date
from django import forms

class DateSelectorWidget(forms.MultiWidget):
    def __init__(self, attrs=None):
        days = [(day, day) for day in range(1, 32)]
        months = [(month, month) for month in range(1, 13)]
        years = [(year, year) for year in [2018, 2019, 2020]]
        widgets = [
            forms.Select(attrs=attrs, choices=days),
            forms.Select(attrs=attrs, choices=months),
            forms.Select(attrs=attrs, choices=years),
        ]
        super().__init__(widgets, attrs)

    def decompress(self, value):
        if isinstance(value, date):
            return [value.day, value.month, value.year]
        elif isinstance(value, str):
            year, month, day = value.split('-')
            return [day, month, year]
        return [None, None, None]

    def value_from_datadict(self, data, files, name):
        day, month, year = super().value_from_datadict(data, files, name)
        # DateField expects a single string that it can parse into a date.
        return '{}-{}-{}'.format(year, month, day)
 The constructor creates several Select widgets in a list. The super() method uses this list to set up the widget. The required method decompress() breaks up a datetime.date value into the day, month, and year values corresponding to each widget. If an invalid date was selected, such as the non-existent 30th February, the DateField passes this method a string instead, so that needs parsing. The final return handles when value is None, meaning we don’t have any defaults for our subwidgets. The default implementation of value_from_datadict() returns a list of values corresponding to each Widget. This is appropriate when using a MultiWidget with a MultiValueField. But since we want to use this widget with a DateField, which takes a single value, we have overridden this method. The implementation here combines the data from the subwidgets into a string in the format that DateField expects.
 Built-in widgets Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in the django.forms.widgets module, including the input of text, various checkboxes and selectors, uploading files, and handling of multi-valued input. Widgets handling input of text These widgets make use of the HTML elements input and textarea. TextInput
class TextInput

input_type: 'text'

template_name: 'django/forms/widgets/text.html'
 Renders as: <input type="text" ...>

 NumberInput
class NumberInput

input_type: 'number'

template_name: 'django/forms/widgets/number.html'
 Renders as: <input type="number" ...>
  Beware that not all browsers support entering localized numbers in number input types. Django itself avoids using them for fields having their localize property set to True.
 EmailInput
class EmailInput

input_type: 'email'

template_name: 'django/forms/widgets/email.html'
 Renders as: <input type="email" ...>

 URLInput
class URLInput

input_type: 'url'

template_name: 'django/forms/widgets/url.html'
 Renders as: <input type="url" ...>

 PasswordInput
class PasswordInput

input_type: 'password'

template_name: 'django/forms/widgets/password.html'
 Renders as: <input type="password" ...>
  Takes one optional argument:
render_value
Determines whether the widget will have a value filled in when the form is re-displayed after a validation error (default is False).

 HiddenInput
class HiddenInput

input_type: 'hidden'

template_name: 'django/forms/widgets/hidden.html'
 Renders as: <input type="hidden" ...>
  Note that there also is a MultipleHiddenInput widget that encapsulates a set of hidden input elements.
 DateInput
class DateInput

input_type: 'text'

template_name: 'django/forms/widgets/date.html'
 Renders as: <input type="text" ...>
  Takes same arguments as TextInput, with one more optional argument:
format
The format in which this field’s initial value will be displayed.
 If no format argument is provided, the default format is the first format found in DATE_INPUT_FORMATS and respects Format localization.
 DateTimeInput
class DateTimeInput

input_type: 'text'

template_name: 'django/forms/widgets/datetime.html'
 Renders as: <input type="text" ...>
  Takes same arguments as TextInput, with one more optional argument:
format
The format in which this field’s initial value will be displayed.
 If no format argument is provided, the default format is the first format found in DATETIME_INPUT_FORMATS and respects Format localization. By default, the microseconds part of the time value is always set to 0. If microseconds are required, use a subclass with the supports_microseconds attribute set to True.
 TimeInput
class TimeInput

input_type: 'text'

template_name: 'django/forms/widgets/time.html'
 Renders as: <input type="text" ...>
  Takes same arguments as TextInput, with one more optional argument:
format
The format in which this field’s initial value will be displayed.
 If no format argument is provided, the default format is the first format found in TIME_INPUT_FORMATS and respects Format localization. For the treatment of microseconds, see DateTimeInput.
 Textarea
class Textarea

template_name: 'django/forms/widgets/textarea.html'
 Renders as: <textarea>...</textarea>

 Selector and checkbox widgets These widgets make use of the HTML elements <select>, <input type="checkbox">, and <input type="radio">. Widgets that render multiple choices have an option_template_name attribute that specifies the template used to render each choice. For example, for the Select widget, select_option.html renders the <option> for a <select>. CheckboxInput
class CheckboxInput

input_type: 'checkbox'

template_name: 'django/forms/widgets/checkbox.html'
 Renders as: <input type="checkbox" ...>
  Takes one optional argument:
check_test
A callable that takes the value of the CheckboxInput and returns True if the checkbox should be checked for that value.

 Select
class Select

template_name: 'django/forms/widgets/select.html'

option_template_name: 'django/forms/widgets/select_option.html'
 Renders as: <select><option ...>...</select>

choices
This attribute is optional when the form field does not have a choices attribute. If it does, it will override anything you set here when the attribute is updated on the Field.

 NullBooleanSelect
class NullBooleanSelect

template_name: 'django/forms/widgets/select.html'

option_template_name: 'django/forms/widgets/select_option.html'
  Select widget with options ‘Unknown’, ‘Yes’ and ‘No’
 SelectMultiple
class SelectMultiple

template_name: 'django/forms/widgets/select.html'

option_template_name: 'django/forms/widgets/select_option.html'
  Similar to Select, but allows multiple selection: <select multiple>...</select>
 RadioSelect
class RadioSelect

template_name: 'django/forms/widgets/radio.html'

option_template_name: 'django/forms/widgets/radio_option.html'
  Similar to Select, but rendered as a list of radio buttons within
 tags:

<input type="radio" name="...">

  ...

  Changed in Django 4.0: So they are announced more concisely by screen readers, radio buttons were changed to render in
 tags.  For more granular control over the generated markup, you can loop over the radio buttons in the template. Assuming a form myform with a field beatles that uses a RadioSelect as its widget: <fieldset>
    <legend>{{ myform.beatles.label }}</legend>
    {% for radio in myform.beatles %}

        {{ radio }}

    {% endfor %}
</fieldset>
 This would generate the following HTML: <fieldset>
    <legend>Radio buttons</legend>

        <input id="id_beatles_0" name="beatles" type="radio" value="john" required> John

        <input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul

        <input id="id_beatles_2" name="beatles" type="radio" value="george" required> George

        <input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo

</fieldset>
 That included the  tags. To get more granular, you can use each radio button’s tag, choice_label and id_for_label attributes. For example, this template… <fieldset>
    <legend>{{ myform.beatles.label }}</legend>
    {% for radio in myform.beatles %}

        {{ radio.choice_label }}
        {{ radio.tag }}

    {% endfor %}
</fieldset>
 …will result in the following HTML: <fieldset>
    <legend>Radio buttons</legend>

        John
        <input id="id_beatles_0" name="beatles" type="radio" value="john" required>

        Paul
        <input id="id_beatles_1" name="beatles" type="radio" value="paul" required>

        George
        <input id="id_beatles_2" name="beatles" type="radio" value="george" required>

        Ringo
        <input id="id_beatles_3" name="beatles" type="radio" value="ringo" required>

</fieldset>
 If you decide not to loop over the radio buttons – e.g., if your template includes {{ myform.beatles }} – they’ll be output in a
 with
 tags, as above. The outer
 container receives the id attribute of the widget, if defined, or BoundField.auto_id otherwise. When looping over the radio buttons, the label and input tags include for and id attributes, respectively. Each radio button has an id_for_label attribute to output the element’s ID.
 CheckboxSelectMultiple
class CheckboxSelectMultiple

template_name: 'django/forms/widgets/checkbox_select.html'

option_template_name: 'django/forms/widgets/checkbox_option.html'
  Similar to SelectMultiple, but rendered as a list of checkboxes:

<input type="checkbox" name="..." >

  ...

 The outer
 container receives the id attribute of the widget, if defined, or BoundField.auto_id otherwise.  Changed in Django 4.0: So they are announced more concisely by screen readers, checkboxes were changed to render in
 tags.
 Like RadioSelect, you can loop over the individual checkboxes for the widget’s choices. Unlike RadioSelect, the checkboxes won’t include the required HTML attribute if the field is required because browser validation would require all checkboxes to be checked instead of at least one. When looping over the checkboxes, the label and input tags include for and id attributes, respectively. Each checkbox has an id_for_label attribute to output the element’s ID. File upload widgets FileInput
class FileInput

template_name: 'django/forms/widgets/file.html'
 Renders as: <input type="file" ...>

 ClearableFileInput
class ClearableFileInput

template_name: 'django/forms/widgets/clearable_file_input.html'
 Renders as: <input type="file" ...> with an additional checkbox input to clear the field’s value, if the field is not required and has initial data.
 Composite widgets MultipleHiddenInput
class MultipleHiddenInput

template_name: 'django/forms/widgets/multiple_hidden.html'
 Renders as: multiple <input type="hidden" ...> tags  A widget that handles multiple hidden widgets for fields that have a list of values.
 SplitDateTimeWidget
class SplitDateTimeWidget

template_name: 'django/forms/widgets/splitdatetime.html'
  Wrapper (using MultiWidget) around two widgets: DateInput for the date, and TimeInput for the time. Must be used with SplitDateTimeField rather than DateTimeField. SplitDateTimeWidget has several optional arguments:
date_format
Similar to DateInput.format

time_format
Similar to TimeInput.format

date_attrs

time_attrs
Similar to Widget.attrs. A dictionary containing HTML attributes to be set on the rendered DateInput and TimeInput widgets, respectively. If these attributes aren’t set, Widget.attrs is used instead.

 SplitHiddenDateTimeWidget
class SplitHiddenDateTimeWidget

template_name: 'django/forms/widgets/splithiddendatetime.html'
  Similar to SplitDateTimeWidget, but uses HiddenInput for both date and time.
 SelectDateWidget
class SelectDateWidget

template_name: 'django/forms/widgets/select_date.html'
  Wrapper around three Select widgets: one each for month, day, and year. Takes several optional arguments:
years
An optional list/tuple of years to use in the “year” select box. The default is a list containing the current year and the next 9 years.

months
An optional dict of months to use in the “months” select box. The keys of the dict correspond to the month number (1-indexed) and the values are the displayed months: MONTHS = {
    1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
    5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
    9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec')
}

empty_label
If the DateField is not required, SelectDateWidget will have an empty choice at the top of the list (which is --- by default). You can change the text of this label with the empty_label attribute. empty_label can be a string, list, or tuple. When a string is used, all select boxes will each have an empty choice with this label. If empty_label is a list or tuple of 3 string elements, the select boxes will have their own custom label. The labels should be in this order ('year_label', 'month_label', 'day_label'). # A custom empty label with string
field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))

# A custom empty label with tuple
field1 = forms.DateField(
    widget=SelectDateWidget(
        empty_label=("Choose Year", "Choose Month", "Choose Day"),
    ),
)


Glossary  (n,)

A parenthesized number followed by a comma denotes a tuple with one element. The trailing comma distinguishes a one-element tuple from a parenthesized n.  -1

In a dimension entry, instructs NumPy to choose the length that will keep the total number of array elements the same. >>> np.arange(12).reshape(4, -1).shape
(4, 3)

In an index, any negative value denotes indexing from the right.   …

An Ellipsis.
When indexing an array, shorthand that the missing axes, if they exist, are full slices. >>> a = np.arange(24).reshape(2,3,4)
 >>> a[...].shape
(2, 3, 4)
 >>> a[...,0].shape
(2, 3)
 >>> a[0,...].shape
(3, 4)
 >>> a[0,...,0].shape
(3,)
 It can be used at most once; a[...,0,...] raises an IndexError.
In printouts, NumPy substitutes ... for the middle elements of large arrays. To see the entire array, use numpy.printoptions
   :

The Python slice operator. In ndarrays, slicing can be applied to every axis: >>> a = np.arange(24).reshape(2,3,4)
>>> a
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],

       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])

>>> a[1:,-2:,:-1]
array([[[16, 17, 18],
        [20, 21, 22]]])
 Trailing slices can be omitted: >>> a[1] == a[1,:,:]
array([[ True,  True,  True,  True],
       [ True,  True,  True,  True],
       [ True,  True,  True,  True]])
 In contrast to Python, where slicing creates a copy, in NumPy slicing creates a view. For details, see Combining advanced and basic indexing.  <

In a dtype declaration, indicates that the data is little-endian (the bracket is big on the right). >>> dt = np.dtype('<f')  # little-endian single-precision float
  >

In a dtype declaration, indicates that the data is big-endian (the bracket is big on the left). >>> dt = np.dtype('>H')  # big-endian unsigned short
  advanced indexing

Rather than using a scalar or slice as an index, an axis can be indexed with an array, providing fine-grained selection. This is known as advanced indexing or “fancy indexing”.  along an axis

An operation along axis n of array a behaves as if its argument were an array of slices of a where each slice has a successive index of axis n. For example, if a is a 3 x N array, an operation along axis 0 behaves as if its argument were an array containing slices of each row: >>> np.array((a[0,:], a[1,:], a[2,:]))
 To make it concrete, we can pick the operation to be the array-reversal function numpy.flip, which accepts an axis argument. We construct a 3 x 4 array a: >>> a = np.arange(12).reshape(3,4)
>>> a
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])
 Reversing along axis 0 (the row axis) yields >>> np.flip(a,axis=0)
array([[ 8,  9, 10, 11],
       [ 4,  5,  6,  7],
       [ 0,  1,  2,  3]])
 Recalling the definition of along an axis, flip along axis 0 is treating its argument as if it were >>> np.array((a[0,:], a[1,:], a[2,:]))
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])
 and the result of np.flip(a,axis=0) is to reverse the slices: >>> np.array((a[2,:],a[1,:],a[0,:]))
array([[ 8,  9, 10, 11],
       [ 4,  5,  6,  7],
       [ 0,  1,  2,  3]])
  array

Used synonymously in the NumPy docs with ndarray.  array_like

Any scalar or sequence that can be interpreted as an ndarray. In addition to ndarrays and scalars this category includes lists (possibly nested and with different element types) and tuples. Any argument accepted by numpy.array is array_like. >>> a = np.array([[1, 2.0], [0, 0], (1+1j, 3.)])

>>> a
array([[1.+0.j, 2.+0.j],
       [0.+0.j, 0.+0.j],
       [1.+1.j, 3.+0.j]])
  array scalar

An array scalar is an instance of the types/classes float32, float64, etc.. For uniformity in handling operands, NumPy treats a scalar as an array of zero dimension. In contrast, a 0-dimensional array is an ndarray instance containing precisely one value.  axis

Another term for an array dimension. Axes are numbered left to right; axis 0 is the first element in the shape tuple. In a two-dimensional vector, the elements of axis 0 are rows and the elements of axis 1 are columns. In higher dimensions, the picture changes. NumPy prints higher-dimensional vectors as replications of row-by-column building blocks, as in this three-dimensional vector: >>> a = np.arange(12).reshape(2,2,3)
>>> a
array([[[ 0,  1,  2],
        [ 3,  4,  5]],
       [[ 6,  7,  8],
        [ 9, 10, 11]]])
 a is depicted as a two-element array whose elements are 2x3 vectors. From this point of view, rows and columns are the final two axes, respectively, in any shape. This rule helps you anticipate how a vector will be printed, and conversely how to find the index of any of the printed elements. For instance, in the example, the last two values of 8’s index must be 0 and 2. Since 8 appears in the second of the two 2x3’s, the first index must be 1: >>> a[1,0,2]
8
 A convenient way to count dimensions in a printed vector is to count [ symbols after the open-parenthesis. This is useful in distinguishing, say, a (1,2,3) shape from a (2,3) shape: >>> a = np.arange(6).reshape(2,3)
>>> a.ndim
2
>>> a
array([[0, 1, 2],
       [3, 4, 5]])
 >>> a = np.arange(6).reshape(1,2,3)
>>> a.ndim
3
>>> a
array([[[0, 1, 2],
        [3, 4, 5]]])
  .base

If an array does not own its memory, then its base attribute returns the object whose memory the array is referencing. That object may be referencing the memory from still another object, so the owning object may be a.base.base.base.... Some writers erroneously claim that testing base determines if arrays are views. For the correct way, see numpy.shares_memory.  big-endian

See Endianness.  BLAS

Basic Linear Algebra Subprograms  broadcast

broadcasting is NumPy’s ability to process ndarrays of different sizes as if all were the same size. It permits an elegant do-what-I-mean behavior where, for instance, adding a scalar to a vector adds the scalar value to every element. >>> a = np.arange(3)
>>> a
array([0, 1, 2])
 >>> a + [3, 3, 3]
array([3, 4, 5])
 >>> a + 3
array([3, 4, 5])
 Ordinarly, vector operands must all be the same size, because NumPy works element by element – for instance, c = a * b is  c[0,0,0] = a[0,0,0] * b[0,0,0]
 c[0,0,1] = a[0,0,1] * b[0,0,1]
...
 But in certain useful cases, NumPy can duplicate data along “missing” axes or “too-short” dimensions so shapes will match. The duplication costs no memory or time. For details, see Broadcasting.  C order

Same as row-major.  column-major

See Row- and column-major order.  contiguous

 An array is contiguous if

 it occupies an unbroken block of memory, and array elements with higher indexes occupy higher addresses (that is, no stride is negative).     copy

See view.  dimension

See axis.  dtype

The datatype describing the (identically typed) elements in an ndarray. It can be changed to reinterpret the array contents. For details, see Data type objects (dtype).  fancy indexing

Another term for advanced indexing.  field

In a structured data type, each subtype is called a field. The field has a name (a string), a type (any valid dtype), and an optional title. See Data type objects (dtype).  Fortran order

Same as column-major.  flattened

See ravel.  homogeneous

All elements of a homogeneous array have the same type. ndarrays, in contrast to Python lists, are homogeneous. The type can be complicated, as in a structured array, but all elements have that type. NumPy object arrays, which contain references to Python objects, fill the role of heterogeneous arrays.  itemsize

The size of the dtype element in bytes.  little-endian

See Endianness.  mask

A boolean array used to select only certain elements for an operation: >>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])
 >>> mask = (x > 2)
>>> mask
array([False, False, False, True,  True])
 >>> x[mask] = -1
>>> x
array([ 0,  1,  2,  -1, -1])
  masked array

Bad or missing data can be cleanly ignored by putting it in a masked array, which has an internal boolean array indicating invalid entries. Operations with masked arrays ignore these entries. >>> a = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
>>> a
masked_array(data=[--, 2.0, --],
             mask=[ True, False,  True],
       fill_value=1e+20)

>>> a + [1, 2, 3]
masked_array(data=[--, 4.0, --],
             mask=[ True, False,  True],
       fill_value=1e+20)
 For details, see Masked arrays.  matrix

NumPy’s two-dimensional matrix class should no longer be used; use regular ndarrays.  ndarray

NumPy’s basic structure.  object array

An array whose dtype is object; that is, it contains references to Python objects. Indexing the array dereferences the Python objects, so unlike other ndarrays, an object array has the ability to hold heterogeneous objects.  ravel

numpy.ravel  and numpy.flatten  both flatten an ndarray. ravel will return a view if possible; flatten always returns a copy. Flattening collapses a multimdimensional array to a single dimension; details of how this is done (for instance, whether a[n+1] should be the next row or next column) are parameters.  record array

A structured array with allowing access in an attribute style (a.field) in addition to a['field']. For details, see numpy.recarray.  row-major

See Row- and column-major order. NumPy creates arrays in row-major order by default.  scalar

In NumPy, usually a synonym for array scalar.  shape

A tuple showing the length of each dimension of an ndarray. The length of the tuple itself is the number of dimensions (numpy.ndim). The product of the tuple elements is the number of elements in the array. For details, see numpy.ndarray.shape.  stride

Physical memory is one-dimensional; strides provide a mechanism to map a given index to an address in memory. For an N-dimensional array, its strides attribute is an N-element tuple; advancing from index i to index i+1 on axis n means adding a.strides[n] bytes to the address. Strides are computed automatically from an array’s dtype and shape, but can be directly specified using as_strided. For details, see numpy.ndarray.strides. To see how striding underlies the power of NumPy views, see The NumPy array: a structure for efficient numerical computation.   structured array

Array whose dtype is a structured data type.  structured data type

Users can create arbitrarily complex dtypes that can include other arrays and dtypes. These composite dtypes are called structured data types.  subarray

An array nested in a structured data type, as b is here: >>> dt = np.dtype([('a', np.int32), ('b', np.float32, (3,))])
>>> np.zeros(3, dtype=dt)
array([(0, [0., 0., 0.]), (0, [0., 0., 0.]), (0, [0., 0., 0.])],
      dtype=[('a', '<i4'), ('b', '<f4', (3,))])
  subarray data type

An element of a structured datatype that behaves like an ndarray.  title

An alias for a field name in a structured datatype.  type

In NumPy, usually a synonym for dtype. For the more general Python meaning, see here.  ufunc

NumPy’s fast element-by-element computation (vectorization) gives a choice which function gets applied. The general term for the function is ufunc, short for universal function. NumPy routines have built-in ufuncs, but users can also write their own.  vectorization

NumPy hands off array processing to C, where looping and computation are much faster than in Python. To exploit this, programmers using NumPy eliminate Python loops in favor of array-to-array operations. vectorization can refer both to the C offloading and to structuring NumPy code to leverage it.  view

Without touching underlying data, NumPy can make one array appear to change its datatype and shape. An array created this way is a view, and NumPy often exploits the performance gain of using a view versus making a new array. A potential drawback is that writing to a view can alter the original as well. If this is a problem, NumPy instead needs to create a physically distinct array – a copy. Some NumPy routines always return views, some always return copies, some may return one or the other, and for some the choice can be specified. Responsibility for managing views and copies falls to the programmer. numpy.shares_memory will check whether b is a view of a, but an exact answer isn’t always feasible, as the documentation page explains. >>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])
 >>> y = x[::2]
>>> y
array([0, 2, 4])
 >>> x[0] = 3 # changing x changes y as well, since y is a view on x
>>> y
array([3, 2, 4])


Using F2PY F2PY can be used either as a command line tool f2py or as a Python module numpy.f2py. While we try to provide the command line tool as part of the numpy setup, some platforms like Windows make it difficult to reliably put the executables on the PATH. We will refer to f2py in this document but you may have to run it as a module: python -m numpy.f2py
 If you run f2py with no arguments, and the line numpy Version at the end matches the NumPy version printed from python -m numpy.f2py, then you can use the shorter version. If not, or if you cannot run f2py, you should replace all calls to f2py here with the longer version.  Command f2py
 When used as a command line tool, f2py has three major modes, distinguished by the usage of -c and -h switches:  Signature file generation
To scan Fortran sources and generate a signature file, use f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
   [ skip: <fortran functions>  : ]]...            \
  [<fortran files> ...]
  Note A Fortran source file can contain many routines, and it is often not necessary to allow all routines be usable from Python. In such cases, either specify which routines should be wrapped (in the only: .. : part) or which routines F2PY should ignored (in the skip: .. : part).  If <filename.pyf> is specified as stdout then signatures are written to standard output instead of a file. Among other options (see below), the following can be used in this mode:  --overwrite-signature

Overwrites an existing signature file.       Extension module construction
To construct an extension module, use f2py -m <modulename> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]              \
   [ skip: <fortran functions>  : ]]...          \
  [<fortran files> ...]
 The constructed extension module is saved as <modulename>module.c to the current directory. Here <fortran files> may also contain signature files. Among other options (see below), the following options can be used in this mode:  --debug-capi

Adds debugging hooks to the extension module. When using this extension module, various diagnostic information about the wrapper is written to the standard output, for example, the values of variables, the steps taken, etc.  -include'<includefile>'

Add a CPP #include statement to the extension module source. <includefile> should be given in one of the following forms "filename.ext"
<filename.ext>
 The include statement is inserted just before the wrapper functions. This feature enables using arbitrary C functions (defined in <includefile>) in F2PY generated wrappers.  Note This option is deprecated. Use usercode statement to specify C code snippets directly in signature files.   --[no-]wrap-functions

Create Fortran subroutine wrappers to Fortran functions. --wrap-functions is default because it ensures maximum portability and compiler independence.  --include-paths <path1>:<path2>:..

Search include files from given directories.  --help-link [<list of resources names>]

List system resources found by numpy_distutils/system_info.py. For example, try f2py --help-link lapack_opt.       Building a module
To build an extension module, use f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
   [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]
 If <fortran files> contains a signature file, then the source for an extension module is constructed, all Fortran and C sources are compiled, and finally all object and library files are linked to the extension module <modulename>.so which is saved into the current directory. If <fortran files> does not contain a signature file, then an extension module is constructed by scanning all Fortran source codes for routine signatures, before proceeding to build the extension module. Among other options (see below) and options described for previous modes, the following options can be used in this mode:  --help-fcompiler

List the available Fortran compilers.
--help-compiler [depreciated]

List the available Fortran compilers.  --fcompiler=<Vendor>

Specify a Fortran compiler type by vendor.  --f77exec=<path>

Specify the path to a F77 compiler
--fcompiler-exec=<path> [depreciated]

Specify the path to a F77 compiler  --f90exec=<path>

Specify the path to a F90 compiler
--f90compiler-exec=<path> [depreciated]

Specify the path to a F90 compiler  --f77flags=<string>

Specify F77 compiler flags  --f90flags=<string>

Specify F90 compiler flags  --opt=<string>

Specify optimization flags  --arch=<string>

Specify architecture specific optimization flags  --noopt

Compile without optimization flags  --noarch

Compile without arch-dependent optimization flags  --debug

Compile with debugging information  -l<libname>

Use the library <libname> when linking.  -D<macro>[=<defn=1>]

Define macro <macro> as <defn>.  -U<macro>

Define macro <macro>  -I<dir>

Append directory <dir> to the list of directories searched for include files.  -L<dir>

Add directory <dir> to the list of directories to be searched for -l.  link-<resource>

Link the extension module with <resource> as defined by numpy_distutils/system_info.py. E.g. to link with optimized LAPACK libraries (vecLib on MacOSX, ATLAS elsewhere), use --link-lapack_opt. See also --help-link switch.    Note The f2py -c option must be applied either to an existing .pyf file (plus the source/object/library files) or one must specify the -m <modulename> option (plus the sources/object/library files). Use one of the following options:  f2py -c -m fib1 fib1.f
 or f2py -m fib1 fib1.f -h fib1.pyf
f2py -c fib1.pyf fib1.f
 For more information, see the Building C and C++ Extensions Python documentation for details. When building an extension module, a combination of the following macros may be required for non-gcc Fortran compilers: -DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN
 To test the performance of F2PY generated interfaces, use -DF2PY_REPORT_ATEXIT. Then a report of various timings is printed out at the exit of Python. This feature may not work on all platforms, currently only Linux platform is supported. To see whether F2PY generated interface performs copies of array arguments, use -DF2PY_REPORT_ON_ARRAY_COPY=<int>. When the size of an array argument is larger than <int>, a message about the coping is sent to stderr.     Other options  -m <modulename>

Name of an extension module. Default is untitled.  Warning Don’t use this option if a signature file (*.pyf) is used.   --[no-]lower

Do [not] lower the cases in <fortran files>. By default, --lower is assumed with -h switch, and --no-lower without the -h switch.  --build-dir <dirname>

All F2PY generated files are created in <dirname>. Default is tempfile.mkdtemp().  --quiet

Run quietly.  --verbose

Run with extra verbosity.  -v

Print the F2PY version and exit.   Execute f2py without any options to get an up-to-date list of available options.    Python module numpy.f2py
  Warning The current Python interface to the f2py module is not mature and may change in the future.  Fortran to Python Interface Generator.   numpy.f2py.compile(source, modulename='untitled', extra_args='', verbose=True, source_fn=None, extension='.f', full_output=False)[source]

Build extension module from a Fortran 77 source string with f2py.  Parameters

sourcestr or bytes

Fortran source of module / subroutine to compile  Changed in version 1.16.0: Accept str as well as bytes
modulenamestr, optional

The name of the compiled python module
extra_argsstr or list, optional

Additional parameters passed to f2py  Changed in version 1.16.0: A list of args may also be provided.
verbosebool, optional

Print f2py output to screen
source_fnstr, optional

Name of the file where the fortran source is written. The default is to use a temporary file with the extension provided by the extension parameter
extension{‘.f’, ‘.f90’}, optional

Filename extension if source_fn is not provided. The extension tells which fortran standard is used. The default is f, which implies F77 standard.  New in version 1.11.0.
full_outputbool, optional

If True, return a subprocess.CompletedProcess containing the stdout and stderr of the compile process, instead of just the status code.  New in version 1.20.0.     Returns

resultint or subprocess.CompletedProcess

0 on success, or a subprocess.CompletedProcess if full_output=True     Examples >>> import numpy.f2py
>>> fsource = '''
...       subroutine foo
...       print*, "Hello world!"
...       end
... '''
>>> numpy.f2py.compile(fsource, modulename='hello', verbose=0)
0
>>> import hello
>>> hello.foo()
 Hello world!

   numpy.f2py.get_include()[source]

Return the directory that contains the fortranobject.c and .h files.  Note This function is not needed when building an extension with numpy.distutils directly from .f and/or .pyf files in one go.  Python extension modules built with f2py-generated code need to use fortranobject.c as a source file, and include the fortranobject.h header. This function can be used to obtain the directory containing both of these files.  Returns

include_pathstr

Absolute path to the directory containing fortranobject.c and fortranobject.h.      See also  numpy.get_include

function that returns the numpy include directory    Notes  New in version 1.22.0.  Unless the build system you are using has specific support for f2py, building a Python extension using a .pyf signature file is a two-step process. For a module mymod:  Step 1: run python -m numpy.f2py mymod.pyf --quiet. This generates _mymodmodule.c and (if needed) _fblas-f2pywrappers.f files next to mymod.pyf.
Step 2: build your Python extension module. This requires the following source files:  _mymodmodule.c
_mymod-f2pywrappers.f (if it was generated in step 1) fortranobject.c
   numpy.f2py.run_main(comline_list)[source]

Equivalent to running: f2py <args>
 where <args>=string.join(<list>,' '), but in Python. Unless -h is used, this function returns a dictionary containing information on generated modules and their dependencies on source files. For example, the command f2py -m scalar scalar.f can be executed from Python as follows You cannot build extension modules with this function, that is, using -c is not allowed. Use compile command instead Examples >>> import numpy.f2py
>>> r = numpy.f2py.run_main(['-m','scalar','doc/source/f2py/scalar.f'])
Reading fortran codes...
        Reading file 'doc/source/f2py/scalar.f' (format:fix,strict)
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print(r)
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py/src/fortranobject.h'],
	 'csrc': ['./scalarmodule.c',
                  '/home/users/pearu/src_cvs/f2py/src/fortranobject.c']}}


Scalars Python defines only one type of a particular data class (there is only one integer type, one floating-point type, etc.). This can be convenient in applications that don’t need to be concerned with all the ways data can be represented in a computer. For scientific computing, however, more control is often needed. In NumPy, there are 24 new fundamental Python types to describe different types of scalars. These type descriptors are mostly based on the types available in the C language that CPython is written in, with several additional types compatible with Python’s types. Array scalars have the same attributes and methods as ndarrays. 1 This allows one to treat items of an array partly on the same footing as arrays, smoothing out rough edges that result when mixing scalar and array operations. Array scalars live in a hierarchy (see the Figure below) of data types. They can be detected using the hierarchy: For example, isinstance(val, np.generic) will return True if val is an array scalar object. Alternatively, what kind of array scalar is present can be determined using other members of the data type hierarchy. Thus, for example isinstance(val, np.complexfloating) will return True if val is a complex valued type, while isinstance(val, np.flexible) will return true if val is one of the flexible itemsize array types (str_, bytes_, void).    Figure: Hierarchy of type objects representing the array data types. Not shown are the two integer types intp and uintp which just point to the integer type that holds a pointer for the platform. All the number types can be obtained using bit-width names as well.    1
However, array scalars are immutable, so none of the array scalar attributes are settable.    Built-in scalar types The built-in scalar types are shown below. The C-like names are associated with character codes, which are shown in their descriptions. Use of the character codes, however, is discouraged. Some of the scalar types are essentially equivalent to fundamental Python types and therefore inherit from them as well as from the generic array scalar type:
Array scalar type Related Python type Inherits?
int_ int Python 2 only
float_ float yes
complex_ complex yes
bytes_ bytes yes
str_ str yes
bool_ bool no
datetime64 datetime.datetime no
timedelta64 datetime.timedelta no   The bool_ data type is very similar to the Python bool but does not inherit from it because Python’s bool does not allow itself to be inherited from, and on the C-level the size of the actual bool data is not the same as a Python Boolean scalar.  Warning The int_ type does not inherit from the int built-in under Python 3, because type int is no longer a fixed-width integer type.   Tip The default data type in NumPy is float_.    class numpy.generic[source]

Base class for numpy scalar types. Class from which most (all?) numpy scalar types are derived. For consistency, exposes the same API as ndarray, despite many consequent attributes being either “get-only,” or completely irrelevant. This is the class from which it is strongly suggested users should derive custom scalar types.
   class numpy.number[source]

Abstract base class of all numeric scalar types.
  Integer types   class numpy.integer[source]

Abstract base class of all integer scalar types.
  Note The numpy integer types mirror the behavior of C integers, and can therefore be subject to Overflow Errors.   Signed integer types   class numpy.signedinteger[source]

Abstract base class of all signed integer scalar types.
   class numpy.byte[source]

Signed integer type, compatible with C char.  Character code
'b'  Alias on this platform (Linux x86_64)
numpy.int8: 8-bit signed integer (-128 to 127).
   class numpy.short[source]

Signed integer type, compatible with C short.  Character code
'h'  Alias on this platform (Linux x86_64)
numpy.int16: 16-bit signed integer (-32_768 to 32_767).
   class numpy.intc[source]

Signed integer type, compatible with C int.  Character code
'i'  Alias on this platform (Linux x86_64)
numpy.int32: 32-bit signed integer (-2_147_483_648 to 2_147_483_647).
   class numpy.int_[source]

Signed integer type, compatible with Python int and C long.  Character code
'l'  Alias on this platform (Linux x86_64)
numpy.int64: 64-bit signed integer (-9_223_372_036_854_775_808 to 9_223_372_036_854_775_807).  Alias on this platform (Linux x86_64)
numpy.intp: Signed integer large enough to fit pointer, compatible with C intptr_t.
   class numpy.longlong[source]

Signed integer type, compatible with C long long.  Character code
'q'
   Unsigned integer types   class numpy.unsignedinteger[source]

Abstract base class of all unsigned integer scalar types.
   class numpy.ubyte[source]

Unsigned integer type, compatible with C unsigned char.  Character code
'B'  Alias on this platform (Linux x86_64)
numpy.uint8: 8-bit unsigned integer (0 to 255).
   class numpy.ushort[source]

Unsigned integer type, compatible with C unsigned short.  Character code
'H'  Alias on this platform (Linux x86_64)
numpy.uint16: 16-bit unsigned integer (0 to 65_535).
   class numpy.uintc[source]

Unsigned integer type, compatible with C unsigned int.  Character code
'I'  Alias on this platform (Linux x86_64)
numpy.uint32: 32-bit unsigned integer (0 to 4_294_967_295).
   class numpy.uint[source]

Unsigned integer type, compatible with C unsigned long.  Character code
'L'  Alias on this platform (Linux x86_64)
numpy.uint64: 64-bit unsigned integer (0 to 18_446_744_073_709_551_615).  Alias on this platform (Linux x86_64)
numpy.uintp: Unsigned integer large enough to fit pointer, compatible with C uintptr_t.
   class numpy.ulonglong[source]

Signed integer type, compatible with C unsigned long long.  Character code
'Q'
    Inexact types   class numpy.inexact[source]

Abstract base class of all numeric scalar types with a (potentially) inexact representation of the values in its range, such as floating-point numbers.
  Note Inexact scalars are printed using the fewest decimal digits needed to distinguish their value from other values of the same datatype, by judicious rounding. See the unique parameter of format_float_positional and format_float_scientific. This means that variables with equal binary values but whose datatypes are of different precisions may display differently: >>> f16 = np.float16("0.1")
>>> f32 = np.float32(f16)
>>> f64 = np.float64(f32)
>>> f16 == f32 == f64
True
>>> f16, f32, f64
(0.1, 0.099975586, 0.0999755859375)
 Note that none of these floats hold the exact value \(\frac{1}{10}\); f16 prints as 0.1 because it is as close to that value as possible, whereas the other types do not as they have more precision and therefore have closer values. Conversely, floating-point scalars of different precisions which approximate the same decimal value may compare unequal despite printing identically: >>> f16 = np.float16("0.1")
>>> f32 = np.float32("0.1")
>>> f64 = np.float64("0.1")
>>> f16 == f32 == f64
False
>>> f16, f32, f64
(0.1, 0.1, 0.1)
   Floating-point types   class numpy.floating[source]

Abstract base class of all floating-point scalar types.
   class numpy.half[source]

Half-precision floating-point number type.  Character code
'e'  Alias on this platform (Linux x86_64)
numpy.float16: 16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa.
   class numpy.single[source]

Single-precision floating-point number type, compatible with C float.  Character code
'f'  Alias on this platform (Linux x86_64)
numpy.float32: 32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa.
   class numpy.double(x=0, /)[source]

Double-precision floating-point number type, compatible with Python float and C double.  Character code
'd'  Alias
numpy.float_  Alias on this platform (Linux x86_64)
numpy.float64: 64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa.
   class numpy.longdouble[source]

Extended-precision floating-point number type, compatible with C long double but not necessarily with IEEE 754 quadruple-precision.  Character code
'g'  Alias
numpy.longfloat  Alias on this platform (Linux x86_64)
numpy.float128: 128-bit extended-precision floating-point number type.
   Complex floating-point types   class numpy.complexfloating[source]

Abstract base class of all complex number scalar types that are made up of floating-point numbers.
   class numpy.csingle[source]

Complex number type composed of two single-precision floating-point numbers.  Character code
'F'  Alias
numpy.singlecomplex  Alias on this platform (Linux x86_64)
numpy.complex64: Complex number type composed of 2 32-bit-precision floating-point numbers.
   class numpy.cdouble(real=0, imag=0)[source]

Complex number type composed of two double-precision floating-point numbers, compatible with Python complex.  Character code
'D'  Alias
numpy.cfloat  Alias
numpy.complex_  Alias on this platform (Linux x86_64)
numpy.complex128: Complex number type composed of 2 64-bit-precision floating-point numbers.
   class numpy.clongdouble[source]

Complex number type composed of two extended-precision floating-point numbers.  Character code
'G'  Alias
numpy.clongfloat  Alias
numpy.longcomplex  Alias on this platform (Linux x86_64)
numpy.complex256: Complex number type composed of 2 128-bit extended-precision floating-point numbers.
    Other types   class numpy.bool_[source]

Boolean type (True or False), stored as a byte.  Warning The bool_ type is not a subclass of the int_ type (the bool_ is not even a number type). This is different than Python’s default implementation of bool as a sub-class of int.   Character code
'?'  Alias
numpy.bool8
   class numpy.datetime64[source]

If created from a 64-bit integer, it represents an offset from 1970-01-01T00:00:00. If created from string, the string can be in ISO 8601 date or datetime format. >>> np.datetime64(10, 'Y')
numpy.datetime64('1980')
>>> np.datetime64('1980', 'Y')
numpy.datetime64('1980')
>>> np.datetime64(10, 'D')
numpy.datetime64('1970-01-11')
 See Datetimes and Timedeltas for more information.  Character code
'M'
   class numpy.timedelta64[source]

A timedelta stored as a 64-bit integer. See Datetimes and Timedeltas for more information.  Character code
'm'
   class numpy.object_[source]

Any Python object.  Character code
'O'
  Note The data actually stored in object arrays (i.e., arrays having dtype object_) are references to Python objects, not the objects themselves. Hence, object arrays behave more like usual Python lists, in the sense that their contents need not be of the same Python type. The object type is also special because an array containing object_ items does not return an object_ object on item access, but instead returns the actual object that the array item refers to.  The following data types are flexible: they have no predefined size and the data they describe can be of different length in different arrays. (In the character codes # is an integer denoting how many elements the data type consists of.)   class numpy.flexible[source]

Abstract base class of all scalar types without predefined length. The actual size of these types depends on the specific np.dtype instantiation.
   class numpy.bytes_[source]

A byte string. When used in arrays, this type strips trailing null bytes.  Character code
'S'  Alias
numpy.string_
   class numpy.str_[source]

A unicode string. When used in arrays, this type strips trailing null codepoints. Unlike the builtin str, this supports the Buffer Protocol, exposing its contents as UCS4: >>> m = memoryview(np.str_("abc"))
>>> m.format
'3w'
>>> m.tobytes()
b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'
  Character code
'U'  Alias
numpy.unicode_
   class numpy.void[source]

Either an opaque sequence of bytes, or a structure. >>> np.void(b'abcd')
void(b'\x61\x62\x63\x64')
 Structured void scalars can only be constructed via extraction from Structured arrays: >>> arr = np.array((1, 2), dtype=[('x', np.int8), ('y', np.int8)])
>>> arr[()]
(1, 2)  # looks like a tuple, but is `np.void`
  Character code
'V'
  Warning See Note on string types. Numeric Compatibility: If you used old typecode characters in your Numeric code (which was never recommended), you will need to change some of them to the new characters. In particular, the needed changes are c -> S1, b -> B, 1 -> b, s -> h, w ->
H, and u -> I. These changes make the type character convention more consistent with other Python modules such as the struct module.    Sized aliases Along with their (mostly) C-derived names, the integer, float, and complex data-types are also available using a bit-width convention so that an array of the right size can always be ensured. Two aliases (numpy.intp and numpy.uintp) pointing to the integer type that is sufficiently large to hold a C pointer are also provided.   numpy.bool8[source]

alias of numpy.bool_
   numpy.int8[source]
  numpy.int16
  numpy.int32
  numpy.int64

Aliases for the signed integer types (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and numpy.longlong) with the specified number of bits. Compatible with the C99 int8_t, int16_t, int32_t, and int64_t, respectively.
   numpy.uint8[source]
  numpy.uint16
  numpy.uint32
  numpy.uint64

Alias for the unsigned integer types (one of numpy.ubyte, numpy.ushort, numpy.uintc, numpy.uint and numpy.ulonglong) with the specified number of bits. Compatible with the C99 uint8_t, uint16_t, uint32_t, and uint64_t, respectively.
   numpy.intp[source]

Alias for the signed integer type (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and np.longlong) that is the same size as a pointer. Compatible with the C intptr_t.  Character code
'p'
   numpy.uintp[source]

Alias for the unsigned integer type (one of numpy.ubyte, numpy.ushort, numpy.uintc, numpy.uint and np.ulonglong) that is the same size as a pointer. Compatible with the C uintptr_t.  Character code
'P'
   numpy.float16[source]

alias of numpy.half
   numpy.float32[source]

alias of numpy.single
   numpy.float64[source]

alias of numpy.double
   numpy.float96
  numpy.float128[source]

Alias for numpy.longdouble, named after its size in bits. The existence of these aliases depends on the platform.
   numpy.complex64[source]

alias of numpy.csingle
   numpy.complex128[source]

alias of numpy.cdouble
   numpy.complex192
  numpy.complex256[source]

Alias for numpy.clongdouble, named after its size in bits. The existence of these aliases depends on the platform.
   Other aliases The first two of these are conveniences which resemble the names of the builtin types, in the same style as bool_, int_, str_, bytes_, and object_:   numpy.float_[source]

alias of numpy.double
   numpy.complex_[source]

alias of numpy.cdouble
 Some more use alternate naming conventions for extended-precision floats and complex numbers:   numpy.longfloat[source]

alias of numpy.longdouble
   numpy.singlecomplex[source]

alias of numpy.csingle
   numpy.cfloat[source]

alias of numpy.cdouble
   numpy.longcomplex[source]

alias of numpy.clongdouble
   numpy.clongfloat[source]

alias of numpy.clongdouble
 The following aliases originate from Python 2, and it is recommended that they not be used in new code.   numpy.string_[source]

alias of numpy.bytes_
   numpy.unicode_[source]

alias of numpy.str_
    Attributes The array scalar objects have an array priority of NPY_SCALAR_PRIORITY (-1,000,000.0). They also do not (yet) have a ctypes attribute. Otherwise, they share the same attributes as arrays:
generic.flags The integer value of flags.
generic.shape Tuple of array dimensions.
generic.strides Tuple of bytes steps in each dimension.
generic.ndim The number of array dimensions.
generic.data Pointer to start of data.
generic.size The number of elements in the gentype.
generic.itemsize The length of one element in bytes.
generic.base Scalar attribute identical to the corresponding array attribute.
generic.dtype Get array data-descriptor.
generic.real The real part of the scalar.
generic.imag The imaginary part of the scalar.
generic.flat A 1-D view of the scalar.
generic.T Scalar attribute identical to the corresponding array attribute.
generic.__array_interface__ Array protocol: Python side
generic.__array_struct__ Array protocol: struct
generic.__array_priority__ Array priority.
generic.__array_wrap__ sc.__array_wrap__(obj) return scalar from array     Indexing  See also Indexing routines, Data type objects (dtype)  Array scalars can be indexed like 0-dimensional arrays: if x is an array scalar,
x[()] returns a copy of array scalar
x[...] returns a 0-dimensional ndarray

x['field-name'] returns the array scalar in the field field-name. (x can have fields, for example, when it corresponds to a structured data type.)    Methods Array scalars have exactly the same methods as arrays. The default behavior of these methods is to internally convert the scalar to an equivalent 0-dimensional array and to call the corresponding array method. In addition, math operations on array scalars are defined so that the same hardware flags are set and used to interpret the results as for ufunc, so that the error state used for ufuncs also carries over to the math on array scalars. The exceptions to the above rules are given below:
generic.__array__ sc.__array__(dtype) return 0-dim array from scalar with specified dtype
generic.__array_wrap__ sc.__array_wrap__(obj) return scalar from array
generic.squeeze Scalar method identical to the corresponding array attribute.
generic.byteswap Scalar method identical to the corresponding array attribute.
generic.__reduce__ Helper for pickle.
generic.__setstate__
generic.setflags Scalar method identical to the corresponding array attribute.   Utility method for typing:
number.__class_getitem__(item, /) Return a parametrized wrapper around the number type.     Defining new types There are two ways to effectively define a new array scalar type (apart from composing structured types dtypes from the built-in scalar types): One way is to simply subclass the ndarray and overwrite the methods of interest. This will work to a degree, but internally certain behaviors are fixed by the data type of the array. To fully customize the data type of an array you need to define a new data-type, and register it with NumPy. Such new types can only be defined in C, using the NumPy C-API.


Parallel Random Number Generation There are three strategies implemented that can be used to produce repeatable pseudo-random numbers across multiple processes (local or distributed).  SeedSequence spawning SeedSequence implements an algorithm to process a user-provided seed, typically as an integer of some size, and to convert it into an initial state for a BitGenerator. It uses hashing techniques to ensure that low-quality seeds are turned into high quality initial states (at least, with very high probability). For example, MT19937 has a state consisting of 624 uint32 integers. A naive way to take a 32-bit integer seed would be to just set the last element of the state to the 32-bit seed and leave the rest 0s. This is a valid state for MT19937, but not a good one. The Mersenne Twister algorithm suffers if there are too many 0s. Similarly, two adjacent 32-bit integer seeds (i.e. 12345 and 12346) would produce very similar streams. SeedSequence avoids these problems by using successions of integer hashes with good avalanche properties to ensure that flipping any bit in the input input has about a 50% chance of flipping any bit in the output. Two input seeds that are very close to each other will produce initial states that are very far from each other (with very high probability). It is also constructed in such a way that you can provide arbitrary-sized integers or lists of integers. SeedSequence will take all of the bits that you provide and mix them together to produce however many bits the consuming BitGenerator needs to initialize itself. These properties together mean that we can safely mix together the usual user-provided seed with simple incrementing counters to get BitGenerator states that are (to very high probability) independent of each other. We can wrap this together into an API that is easy to use and difficult to misuse. from numpy.random import SeedSequence, default_rng

ss = SeedSequence(12345)

# Spawn off 10 child SeedSequences to pass to child processes.
child_seeds = ss.spawn(10)
streams = [default_rng(s) for s in child_seeds]
 Child SeedSequence objects can also spawn to make grandchildren, and so on. Each SeedSequence has its position in the tree of spawned SeedSequence objects mixed in with the user-provided seed to generate independent (with very high probability) streams. grandchildren = child_seeds[0].spawn(4)
grand_streams = [default_rng(s) for s in grandchildren]
 This feature lets you make local decisions about when and how to split up streams without coordination between processes. You do not have to preallocate space to avoid overlapping or request streams from a common global service. This general “tree-hashing” scheme is not unique to numpy but not yet widespread. Python has increasingly-flexible mechanisms for parallelization available, and this scheme fits in very well with that kind of use. Using this scheme, an upper bound on the probability of a collision can be estimated if one knows the number of streams that you derive. SeedSequence hashes its inputs, both the seed and the spawn-tree-path, down to a 128-bit pool by default. The probability that there is a collision in that pool, pessimistically-estimated (1), will be about \(n^2*2^{-128}\) where n is the number of streams spawned. If a program uses an aggressive million streams, about \(2^{20}\), then the probability that at least one pair of them are identical is about \(2^{-88}\), which is in solidly-ignorable territory (2).  1
The algorithm is carefully designed to eliminate a number of possible ways to collide. For example, if one only does one level of spawning, it is guaranteed that all states will be unique. But it’s easier to estimate the naive upper bound on a napkin and take comfort knowing that the probability is actually lower.  2
In this calculation, we can mostly ignore the amount of numbers drawn from each stream. See Upgrading PCG64 with PCG64DXSM for the technical details about PCG64. The other PRNGs we provide have some extra protection built in that avoids overlaps if the SeedSequence pools differ in the slightest bit. PCG64DXSM has \(2^{127}\) separate cycles determined by the seed in addition to the position in the \(2^{128}\) long period for each cycle, so one has to both get on or near the same cycle and seed a nearby position in the cycle. Philox has completely independent cycles determined by the seed. SFC64 incorporates a 64-bit counter so every unique seed is at least \(2^{64}\) iterations away from any other seed. And finally, MT19937 has just an unimaginably huge period. Getting a collision internal to SeedSequence is the way a failure would be observed.     Independent Streams Philox is a counter-based RNG based which generates values by encrypting an incrementing counter using weak cryptographic primitives. The seed determines the key that is used for the encryption. Unique keys create unique, independent streams. Philox lets you bypass the seeding algorithm to directly set the 128-bit key. Similar, but different, keys will still create independent streams. import secrets
from numpy.random import Philox

# 128-bit number as a seed
root_seed = secrets.getrandbits(128)
streams = [Philox(key=root_seed + stream_id) for stream_id in range(10)]
 This scheme does require that you avoid reusing stream IDs. This may require coordination between the parallel processes.   Jumping the BitGenerator state jumped advances the state of the BitGenerator as-if a large number of random numbers have been drawn, and returns a new instance with this state. The specific number of draws varies by BitGenerator, and ranges from \(2^{64}\) to \(2^{128}\). Additionally, the as-if draws also depend on the size of the default random number produced by the specific BitGenerator. The BitGenerators that support jumped, along with the period of the BitGenerator, the size of the jump and the bits in the default unsigned random are listed below.
BitGenerator Period Jump Size Bits per Draw
MT19937 \(2^{19937}-1\) \(2^{128}\) 32
PCG64 \(2^{128}\) \(~2^{127}\) (3) 64
PCG64DXSM \(2^{128}\) \(~2^{127}\) (3) 64
Philox \(2^{256}\) \(2^{128}\) 64
3(1,2)

The jump size is \((\phi-1)*2^{128}\) where \(\phi\) is the golden ratio. As the jumps wrap around the period, the actual distances between neighboring streams will slowly grow smaller than the jump size, but using the golden ratio this way is a classic method of constructing a low-discrepancy sequence that spreads out the states around the period optimally. You will not be able to jump enough to make those distances small enough to overlap in your lifetime.   jumped can be used to produce long blocks which should be long enough to not overlap. import secrets
from numpy.random import PCG64

seed = secrets.getrandbits(128)
blocked_rng = []
rng = PCG64(seed)
for i in range(10):
    blocked_rng.append(rng.jumped(i))
 When using jumped, one does have to take care not to jump to a stream that was already used. In the above example, one could not later use blocked_rng[0].jumped() as it would overlap with blocked_rng[1]. Like with the independent streams, if the main process here wants to split off 10 more streams by jumping, then it needs to start with range(10, 20), otherwise it would recreate the same streams. On the other hand, if you carefully construct the streams, then you are guaranteed to have streams that do not overlap.