docs: add container types documentation (#3349) by coderay3000 · Pull Request #10775 · numba/numba

coderay3000 · 2026-08-12T13:41:44Z

Description

This PR adds documentation for Numba's strongly-typed containers (ListType and DictType) under a new Containers section in docs/source/reference/types.rst.

Changes Made

Added a Containers subsection under Types and signatures in types.rst.
Added directive-based documentation (.. class::) and usage examples for numba.types.ListType and numba.types.DictType.
Applied standard reStructuredText (RST) formatting aligned with existing reference documentation.

Related Issue

Closes #3349

AI / LLM Disclosure

Google Gemini was used as an AI assistant to help format the reStructuredText (.rst) syntax and verify doc directives. All generated content and formatting were manually reviewed and validated prior to submission.

coderay3000 · 2026-08-12T16:58:13Z

Update on CI failure:

The Sphinx build in CI was failing due to an undefined reference label (undefined label: 'withobjmode').

I have updated line 121 in types.rst to format numba.objmode as an inline code block instead of using an invalid :ref: tag. The Sphinx build issue is now resolved.

coderay3000 · 2026-08-12T20:25:58Z

Hi @swap357,

I've resolved all the CI check failures:

Fixed the Sphinx broken reference label issue by formatting numba.objmode as an inline code block.
Renamed the release note fragment to 10775.doc.rst matching the PR ID.

All checks are now green. Please review when you get a chance!

kc611 · 2026-08-17T11:40:47Z

Hi @coderay3000,

Thank you for PR and making contributions to Numba!

Could you please address the errors on the CI jobs ?

This can be done by making the Release Note of form:

<Heading>
-----------

<Description>

For example: https://github.com/numba/numba/blob/main/docs/upcoming_changes/10528.bug_fix.rst

coderay3000 · 2026-08-17T11:44:31Z

Hi @kc611,

Thank you! I have updated the release note fragment (10775.doc.rst) to follow the proper heading format (<Heading> with underline) and minimum line requirements. All CI checks are now passing!

esc

@coderay3000 thank you for submitting this PR!

I would like to request three changes:

a) The containers are documented already: https://numba.readthedocs.io/en/stable/reference/pysupported.html#typed-list -- so just mention the types here and then create a link to the already exitsting documentation.

b) There is also a typed set, please add that type here too.

c) The towncrier snippet is incorrectly formatted, please take a look and fix this.

Feel free to followup with questions, in case the above is not clear.

swap357

Found a problem with sample on DictType-

swap357 · 2026-08-18T14:35:25Z

+
+      >>> from numba import types, typed
+      >>> dict_type = types.DictType(types.unicode_type, types.int64)
+      >>> typed.Dict.empty_dict(types.unicode_type, types.int64)


the sample here is incorrect. There's no typed.Dict.empty_dict:

>>> from numba import types, typed >>> dict_type = types.DictType(types.unicode_type, types.int64) >>> typed.Dict.empty_dict(types.unicode_type, types.int64) Traceback (most recent call last): File "<python-input-2>", line 1, in <module> typed.Dict.empty_dict(types.unicode_type, types.int64) ^^^^^^^^^^^^^^^^^^^^^ AttributeError: type object 'Dict' has no attribute 'empty_dict'

as @esc mentioned, the documentation with sample snippets is on - https://numba.readthedocs.io/en/stable/reference/pysupported.html
that can be used as reference.

coderay3000 · 2026-08-18T16:17:35Z

Hi @esc,

Thanks for the detailed review! I have updated the PR according to your suggestions:

Containers & Links: Updated types.rst to document ListType, DictType, and SetType with direct :ref: links pointing to their existing documentation sections.
Typed Set: Included numba.types.SetType alongside ListType and DictType.
Towncrier Snippet: Properly created and formatted the release note snippet at docs/upcoming_changes/10775.doc.rst.

All changes have been committed and pushed. Please take a look when you get a chance!

coderay3000 · 2026-08-18T16:19:09Z

Hi @swap357,

Thanks for pointing that out!

As per the feedback from you and @esc, I have completely removed the sample code snippets from types.rst and replaced them with direct cross-references (:ref:) pointing to the existing documentation in pysupported.html.

The updated changes are pushed and ready for review!

esc

Thank you for the updates, one final nitpick to resolve, then OK to merge!

Thank you for the patch ❤️

esc

This underline style is to be preferred.

Co-authored-by: Emergency Self-Construct <esc@users.noreply.github.com>

esc · 2026-08-18T19:36:53Z

@@ -0,0 +1,4 @@
+Document container types in reference manual
+-----------------------------------------------------------


Yeah, so sorry, this needs to be the same length as the text above.

No problem at all! I've updated the underline length to match the title exactly. Thanks @esc!

Yes, but you used = instead of -...

oh, I see, you fixed it later on, thank you.

You're welcome! Apologies for the initial confusion with the formatting and references. I've updated everything according to the guidelines, and all CI checks are green now.

Thanks a lot for your patience and guidance!

requested changes were made

esc

Thank you for the patch!

coderay3000 · 2026-08-19T10:31:19Z

Happy to contribute! Thanks for merging.

coderay3000 added 5 commits August 12, 2026 19:05

docs: add container types documentation (numba#3349)

6300932

docs: add release note fragment for numba#3349

3ed142d

docs: fix formatting and remove non-breaking spaces in types.rst

874049b

docs: fix broken reference label objmode to withobjmode

0ae9757

docs: remove invalid ref tag and format objmode as code block

a73a230

swap357 added the 2 - In Progress label Aug 12, 2026

coderay3000 added 2 commits August 13, 2026 01:20

docs: rename release note extension to .doc.rst for towncrier

b9cb46f

docs: rename release note fragment to use PR ID 10775

ca89496

kc611 added 3 - Ready for Review doc 2 - In Progress and removed 2 - In Progress 3 - Ready for Review labels Aug 17, 2026

docs: clean up release note formatting and line count

f89feff

kc611 requested a review from esc August 18, 2026 14:35

esc requested changes Aug 18, 2026

View reviewed changes

esc added 4 - Waiting on author Waiting for author to respond to review and removed 2 - In Progress labels Aug 18, 2026

swap357 previously requested changes Aug 18, 2026

View reviewed changes

coderay3000 added 2 commits August 18, 2026 21:38

docs: clean up container types formatting and refs

23ea6f3

docs: document container types and add release note snippet

2b77911

coderay3000 requested review from esc and swap357 August 18, 2026 16:50

docs: fix ref syntax and label for container types

20b89dc

esc requested changes Aug 18, 2026

View reviewed changes

Comment thread docs/upcoming_changes/10775.doc.rst Outdated

esc requested changes Aug 18, 2026

View reviewed changes

Comment thread docs/upcoming_changes/10775.doc.rst Outdated

coderay3000 and others added 2 commits August 19, 2026 01:02

Update docs/upcoming_changes/10775.doc.rst

e4faffa

Co-authored-by: Emergency Self-Construct <esc@users.noreply.github.com>

Update docs/upcoming_changes/10775.doc.rst

634f37d

Co-authored-by: Emergency Self-Construct <esc@users.noreply.github.com>

esc requested changes Aug 18, 2026

View reviewed changes

docs: match underline length in release snippet

1a54fa2

coderay3000 requested a review from esc August 18, 2026 20:04

coderay3000 added 2 commits August 19, 2026 08:42

docs: fix towncrier hyphens and correct list ref label

1a8fbf8

docs: fix sphinx ref targets to feature-typed

6802228

esc approved these changes Aug 19, 2026

View reviewed changes

esc merged commit 41fbb29 into numba:main Aug 19, 2026
24 checks passed

coderay3000 deleted the docs/container-types-3349 branch August 19, 2026 10:31

		@@ -0,0 +1,4 @@
		Document container types in reference manual
		-----------------------------------------------------------

Conversation

coderay3000 commented Aug 12, 2026

Description

Changes Made

Related Issue

AI / LLM Disclosure

Uh oh!

coderay3000 commented Aug 12, 2026

Uh oh!

coderay3000 commented Aug 12, 2026

Uh oh!

kc611 commented Aug 17, 2026

Uh oh!

coderay3000 commented Aug 17, 2026

Uh oh!

esc left a comment

Choose a reason for hiding this comment

Uh oh!

swap357 left a comment

Choose a reason for hiding this comment

Uh oh!

swap357 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

swap357 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

coderay3000 commented Aug 18, 2026

Uh oh!

coderay3000 commented Aug 18, 2026

Uh oh!

esc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

esc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

esc Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

coderay3000 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

esc Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

esc Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

coderay3000 Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

esc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderay3000 commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants