jprzywoski / python-reference Goto Github PK

https://python-reference.readthedocs.io/en/latest/docs/dict/
In this page it said that ,
"Dictionaries are mutable unordered collections (they do not record element position or order of insertion) of key-value pairs. Keys within the dictionary must be unique and must be hashable. That includes types like numbers, strings and tuples. Lists and dicts can not be used as keys since they are mutable. Dictionaries in other languages are also called hash tables or associative arrays."

However on the new updates
Dictionaries are insertion-ordered. This means the order in which key-value pairs are added to the dictionary is preserved when iterating over it.

Example 3 on seek documentation uses negative offset to read last 3 bytes of the file. The seek function in python doesn't support negative indexing.

THIS IS AN AWESOME PROJECT THANK YOU.

Opening an issue because the first page I found was this:
https://python-reference.readthedocs.io/en/latest/docs/brackets/slicing.html

A few suggestions to give this Doc have a better flow.

Problems:

1. The breadcrumbs do not allow you to navigate up to the parent section.
2. The Sidebar TOC has no highlighted entry on this page, which was disorienting for me. This was the first page of this documentation I encountered (arrived via a Google search).

From the index page (https://python-reference.readthedocs.io/en/latest/index.html)
you cannot ctrl+f to search and find "[]" nor "slicing",
since the [] (slicing) page is a child of Container Data Access -> [subsection] Brackets Operators.

So the unfamiliar user needs to explore or sift to find the position of the [] (slicing) page in the greater context.

More Details:

Breadcrumbs:

In the sphinx_rtd_theme, breadcrumbs are the area at the top of the main page block in the upper-left corner (in the same row as the "Edit on GitHub" link).

The breadcrumbs for the [] (slicing) page read:

• Docs » [] (slicing)

Instead, the breadcrumbs for this page should ideally contain:

• Docs » Container Data Access » [] (slicing)

TOC Entry:

There is no Sidebar TOC item selected on this page.

Ideally Container Data Access should be selected as the active Sidebar TOC listview item, and [] (slicing) should be a subnode / subsection item under Container Data Access.

Solution:

Both of these can be implemented in one go:

Currently the /docs/brackets/index.rst page contains hardcoded links to its children sections.

If you replace these hardcoded section label links with with a TOC Tree Directive inside the page /docs/brackets/index.rst like this:

.. toctree::
   :maxdepth: -1
   
   brackets/indexing.rst
   brackets/slicing.rst
   brackets/key_lookup.rst
   brackets/ellipsis.rst

Then:

• When /docs/brackets/index.rst is included in the .. toctree:: of /index.rst, it's children will auto-populate inside the main index homepage TOC, and sphinx_rtd_theme will ALSO auto add these entries to the Sidebar TOC. (You do not need to modify /index.rst for this implementation, only modify /docs/brackets/index.rst.)
• (and I believe sphinx_rtd_theme will auto-generate the breadcrumbs for you too).

Note: The syntax might work as-is in my codeblock example, but I didn't test it. My syntax might be off / I might have gotten the link paths wrong.

Short on time, but this is the general technique / recipe.

Thanks for this!

Again, this is an awesome project.

Cramming Python right now, awesome resource, many thanks!

The Remarks Section says

Equivalent to A = A + B.

But that is not true. += operator uses __iadd__ method, if it is defined.
If it's not defined, then it uses the __add__ method.

__iadd__ method does addition in place.
__add__ method adds the two objects and returns a new object.

In depth discussion can be found here : https://stackoverflow.com/a/2347423/13345708

The Remarks can be edited to say

Equivalent to A = A + B, if iadd method is not defined

This should mention the new behavior of python 3, which is not to return an integer for integer division.

Two typos here
<<= (bitwise right shift assignment)
and
>>= (bitwise left shift assignment)

It would be very handy if isdisjoint() could have its own operator symbol,
aka, delicious Python syntax sugar - many thanks!

I understand the need for this project and I appreciate it. The official Python documentation isn't easy to use.

I see that this project hasn't been updated since 2015. I know it must be a big task to edit the Python documentation and keep this project in sync with changes in Python. Have you considered making the building of this documentation more programmatic? That is, instead of writing many new documentation files, use the official documentation files, arranging them in a convenient order and patching them with additional information like helpful examples.

Mention that sorting is stable:

• https://python-reference.readthedocs.io/en/latest/docs/functions/sorted.html
• https://python-reference.readthedocs.io/en/latest/docs/list/sort.html

This is an important property to know when using these sorting functions.

Also see: https://docs.python.org/3/howto/sorting.html

Using Python 3.10.7 with syntax of: mysplitstr = 'string'.split(',')[4]
'string' example [ '1, 2, 3, 4, 5ormore']
script execution of string'.split(',')[4] returns [ '5ormore' ]
More experimenting indicates the function of [max split] is selection of returned value.
Split uses index starting at 0 based so string example has 4 items.
When [max split] is larger than number of split items an exception occurs.

Hello!

https://github.com/jprzywoski/python-reference/blob/master/source/docs/operators/assignment.rst#example-2

We have description "First the integer 10 is assigned to the variable c, then the value of c (10) is assigned to b and b is assigned to a" for a = b = c = 10 expression.
The right order: "assigns the single resulting object to each of the target lists, from left to right" (https://docs.python.org/3/reference/simple_stmts.html#assignment-statements)

Have a nice day!

File location: python-reference/source/docs/str/formatting.rst.

In Syntax %[key][flags][width][.precision][length type]conversion type % values,
the conversion type is not optional.
It should be Required, which marks the end of the specifier.

I think only the fields in square brackets are optional.

Corresponding docs: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting