Opened 4 years ago

Closed 4 years ago

#31744 closed Cleanup/optimization (wontfix)

Pydoc support/helper

Reported by: Sardorbek Imomaliev Owned by: nobody
Component: Core (Other) Version: 3.0
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Currently pydoc doesn't work by default because it requires django requries django.setup() to be called. So to use it you need to provide some helper script like in this example https://stackoverflow.com/questions/24772805/python-documentation-for-django-views-generic-with-pydoc

import django
import pydoc
import os

os.environ['DJANGO_SETTINGS_MODULE'] = 'dummy.settings'
django.setup()
pydoc.cli()

Another issue(probably need to create separate for this one) is that when GDAL is not installed you can't use pydoc even after you have added helper script, because GDAL has to be setup properly on import and there is no way to make django skip this check. This also prevents running code analyzing tools like mypy on django without GDAL, which I don't think is required for running linters.

I don't know how many people are still using pydoc. But I think this should be supported because it is internal python documentation tool. How can I help with resolving this? Maybe django should provide management command for this?

Change History (4)

comment:1 by Mariusz Felisiak, 4 years ago

pydoc works perfectly fine for me, e.g.

$ pip install Django
$ pydoc django.views.generic

Help on package django.views.generic in django.views:

NAME
    django.views.generic

PACKAGE CONTENTS
    base
    dates
    detail
    edit
    list

CLASSES
    builtins.Exception(builtins.BaseException)
...

comment:2 by Sardorbek Imomaliev, 4 years ago

Issue occurs when trying to lookup models

python -mpydoc django.contrib.auth.models
problem in django.contrib.auth.models - 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.

comment:3 by Sardorbek Imomaliev, 4 years ago

Also for gis

python -mpydoc django.contrib.gis.db.models
problem in django.contrib.gis.db.models - ImproperlyConfigured: Could not find the GDAL library (tried "gdal", "GDAL", "gdal2.3.0", "gdal2.2.0", "gdal2.1.0", "gdal2.0.0", "gdal1.11.0"). Is GDAL installed? If it is, try setting GDAL_LIBRARY_PATH in your settings.

comment:4 by Mariusz Felisiak, 4 years ago

Component: DocumentationCore (Other)
Resolution: wontfix
Status: newclosed
Type: UncategorizedCleanup/optimization

Yes, that's true. pydoc just like sphinx.ext.viewcode (see #29942) imports modules, that's why it will crash when required packages are missing or if settings are not configured. Setting DJANGO_SETTINGS_MODULE fixes this issue in most cases. I don't see a clear path to solve this in Django. I'm against adding a new management command for pydoc and adding multiple if __name__ == ... seems clunky and decrease code readability.

Maybe a discussion on DevelopersMailingList will bring some ideas, but I don't think it's feasible without side-effects.

Thanks for the report.

Note: See TracTickets for help on using tickets.
Back to Top