[GH-ISSUE #1115] Improve 'util.py' with function docstrings #661

New issue

Closed

opened 2026-02-28 00:00:39 +03:00 by kerem · 4 comments

kerem commented

2026-02-28 00:00:39 +03:00

Owner

Originally created by @dianna-SE on GitHub (May 22, 2024).
Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1115

Description of feature request
I was analyzing this file for a course in my post-baccalaureate program and conducted several tests, but found it difficult to understand the function's purpose, parameters, and variables. Following basic coding style guidelines, there is an inconsistency with function docstrings (only one docstring was included for a function but not the rest). The lack of documentation made it difficult to work/test with the code.

Solution description
Maintain consistency with function docstrings and provide clear details that describe the function's purpose, parameters, return values, and error handling, if any.

Alternatives considered
I tried to read through the code and ran tests, but it was time-consuming to read through the code to try to understand the function's purpose. This resulted in slight errors and delayed the time to conduct thorough testing.

Additional context
Improving the documentation of the functions will improve readability and allow other users to better understand and maintain the code, especially for testing.

Originally created by @dianna-SE on GitHub (May 22, 2024). Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1115 **Description of feature request** I was analyzing this file for a course in my post-baccalaureate program and conducted several tests, but found it difficult to understand the function's purpose, parameters, and variables. Following basic coding style guidelines, there is an inconsistency with function docstrings (only one docstring was included for a function but not the rest). The lack of documentation made it difficult to work/test with the code. **Solution description** Maintain consistency with function docstrings and provide clear details that describe the function's purpose, parameters, return values, and error handling, if any. **Alternatives considered** I tried to read through the code and ran tests, but it was time-consuming to read through the code to try to understand the function's purpose. This resulted in slight errors and delayed the time to conduct thorough testing. **Additional context** Improving the documentation of the functions will improve readability and allow other users to better understand and maintain the code, especially for testing.

kerem

2026-02-28 00:00:39 +03:00

closed this issue
added the
enhancement
label

kerem commented

2026-02-28 00:00:40 +03:00

Author

Owner

@dieser-niko commented on GitHub (May 23, 2024):

This can be explained somewhat easily, as the functions aren't that big.

normalize_scope makes sure that the input is a list/tuple. If the input (scope) is a string, it splits the string by commas to create a list of scopes. If the scope is already a list or tuple, it uses it directly.

get_host_port splits something like "localhost:8080" into host and port and returns it as a tuple ("localhost", 8080). If no port is given, then it returns ("localhost", None).

But I have to agree with you, docstrings should be mandatory for every function.

@dieser-niko commented on GitHub (May 23, 2024): This can be explained somewhat easily, as the functions aren't that big. `normalize_scope` makes sure that the input is a list/tuple. If the input (scope) is a string, it splits the string by commas to create a list of scopes. If the scope is already a list or tuple, it uses it directly. `get_host_port` splits something like `"localhost:8080"` into host and port and returns it as a tuple `("localhost", 8080)`. If no port is given, then it returns `("localhost", None)`. But I have to agree with you, docstrings should be mandatory for every function.

kerem commented

2026-02-28 00:00:40 +03:00

Author

Owner

@dianna-SE commented on GitHub (May 24, 2024):

I think your explanation sums up as a great docstring explanation for these functions actually! They are simple but beginners or developers unfamiliar with Python would find them incredibly helpful.

@dianna-SE commented on GitHub (May 24, 2024): I think your explanation sums up as a great docstring explanation for these functions actually! They are simple but beginners or developers unfamiliar with Python would find them incredibly helpful.

kerem commented

2026-02-28 00:00:40 +03:00

Author

Owner

@dieser-niko commented on GitHub (May 24, 2024):

I think you meant Python instead of JavaScript

@dieser-niko commented on GitHub (May 24, 2024): I think you meant Python instead of JavaScript

kerem commented

2026-02-28 00:00:40 +03:00

Author

Owner

@dianna-SE commented on GitHub (May 25, 2024):