Should pydoc document automatically created file?

Question

I try to understand how pydoc works, and wanted to have it display the docstring of a file.

I have an unaltered file urls.py (created using Django, but that seems irrelevant for my pydoc question):

"""box_whiskers_demo URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/3.1/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
]

But the following command issued in a python prompt

import urls

gives me the error message django.core.exceptions.ImproperlyConfigured: Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings. django.core.exceptions.ImproperlyConfigured: Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings. . What I expected was that Similarly, the command

from urls import urlpatterns

gives me exactly the same error message.

I supposed that I could get Python to read the file, then access the docstring, as I can with

import pydoc
help(pydoc)

The latter outputs meaningful, error-free documentation. Knowing that the file urls.py is no module, I read

If the argument to pydoc looks like a path (that is, it contains the path separator for your operating system, such as a slash in Unix), and refers to an existing Python source file, then documentation is produced for that file.

in the pydoc documentation , and "that file" has a fine, multi-line docstring.

Does the error imply, that "that file" is neither a

name of a function, module, or package

or does the error originate somewhere else? Should I expect the docstring as output from any of these pydoc call at all?

Answer 1

I think I managed to nail down the problem: As Python looked for the admin package, and did not find it, the problems started. Thus with commenting out the statement calling for admin. , using

urlpatterns = [
#    path('admin/', admin.site.urls),
]

My call from bash

pydoc urls

gives me beautiful docstring:

Help on module urls:

NAME
    urls - box_whiskers_demo URL Configuration

DESCRIPTION
    The `urlpatterns` list routes URLs to views. For more information please see:
        https://docs.djangoproject.com/en/3.1/topics/http/urls/
    Examples:
    Function views
        1. Add an import:  from my_app import views
        2. Add a URL to urlpatterns:  path('', views.home, name='home')
    Class-based views
        1. Add an import:  from other_app.views import Home
        2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
    Including another URLconf
        1. Import the include() function: from django.urls import include, path
        2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))

DATA
    path = functools.partial(<function _path at 0x7f3c9b88d...ern=<class '...
    urlpatterns = []

FILE
    /home/morten/Dropbox/Python/django/box_whiskers_demo/box_whiskers_demo/urls.py

(END)

NB I get the exact same output with the following sequence from inside a python command:

import urls
help(urls)