Improving Windows users experience at the command line

[Ramiro Morales]

Hi all,

Tim Graham suggested to post this to this mailing list.

Currently, users of Django on Windows have a less than ideal experience hen using the command line. The users mailing list still see posts of new users suffering problems like:

- I run django-admin.py startproject and I get an error message stating django-admin.py isn't a known command

(This is usually because the <Python install dir>\Scripts\ path isn't listed in the PATH environment variable.)

- I run django-admin.py startproject as directed and a text editor window opens containing  Python code (source code of django-admin.py).

(This is usually because the user somehow had the .py extension associated to such editor in their OS-maintained mapping DB of file extensions -> Programs.)

- I run python django-admn.py startproject and I get an error message stating Python isn't a known command

(This is because the directory containing python.exe hasn't been added to the PATH environment variable.)

And similar issues.

As we know, versions of Python supported by the currently WIP  version of Django [1]will be 3.5 or newer.

Also, since version 3.3, the official Windows Python installer [2]includes an implementation of the 'Windows python launcher' proposed by [3]PEP 397. This tool gets installed to a system directory always present in PATH and can act a a pivot to get scripts like django-admin.py, manage.py and runtests.py executed by the right Python interpreter binary, even when running inside a virtual environment.

This led me to think it would be possible to simplify lives of our Windows users because today, with a default installation of Python 3.5 o 3.6 (tested this with Python 3.5 on a Windows 7 system) Windows users can simply write

django-admin.py startproject foo

And things Just work (TM). be it either using the global interpreter, or using a virtual enviromnent.

Ticket is #28343: https://code.djangoproject.com/ticket/28343

PR is #8684: https://github.com/django/django/pull/8684

The PR also modifies the introductory document for contributors to Django so it stops suggesting Windows users to use the alien Git Bash shell. At first is seems like a good idea but considering facts like

- It forces users to type in "Unixisms" like `./manage.py` or `mkdir ~/.virtualenvs`

- Is incompatible with venv (another useful tool, also new in Python 3.3 as part of the standard library) and forces the document to divert Windows users so they install and use virtualenv, putting them in the strange situation of having to do that because then they can activate the virtual env by using the Unix shell-specific `source` builtin instead of using native scripts activate.bat or activate.ps1

Another change proposed by the PR is the addition of a custom Sphinx directive that modifies the UI of CLI example text boxes so they can show a native prompt and native command line input as it should actually be typed by the user either on Unix-based shells or the Windows command prompt through a tabbed interface.

A small demo of the proposed change is here (as would be seen on the docs.djangoproject.com website) is here:

http://imgur.com/3ce03UT

Feedback is welcome.

Regards,

1. https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
2. https://docs.python.org/3.5/using/windows.html#python-launcher-for-windows
3. https://www.python.org/dev/peps/pep-0397/

--

Ramiro Morales
@ramiromorales

[Florian Apolloner]

Hi Ramiro,

On Tuesday, July 11, 2017 at 10:55:38 PM UTC+2, Ramiro Morales wrote:

- I run django-admin.py startproject and I get an error message stating django-admin.py isn't a known command

FWIW django-admin.py shouldn't be used any more nowadays -- my latest changes should install django-admin.exe (https://github.com/django/django/blob/d7881d2020a7337ed128eeef811ef1c1e549b481/setup.py#L48). That said, yes it is a problem that the location of those commands is probably not on any executable path in windows. For fairness' sake, the same applies for `pip install --user` on linux -- although not that much of a problem since most users just use sudo to install 🙈.

- I run django-admin.py startproject as directed and a text editor window opens containing  Python code (source code of django-admin.py).

LMAO *scnr*, does the same actually apply if the exe variant is used? I am asking because the tutorial clearly mentions django-admin (https://docs.djangoproject.com/en/1.11/intro/tutorial01/#creating-a-project) without the .py suffix.
 

- I run python django-admn.py startproject and I get an error message stating Python isn't a known command

See above, if django-admin is used instead of django-admin.py there should be no problems
 

django-admin.py startproject foo

That seems already to be the case (minus the .py which is no longer needed). manage.py might still be a problem though.
 

- It forces users to type in "Unixisms" like `./manage.py` or `mkdir ~/.virtualenvs`

+1, there are certainly still unix variants of commands there which should be changed to something accommodating for all platforms.

- Is incompatible with venv (another useful tool, also new in Python 3.3 as part of the standard library) and forces the document to divert Windows users so they install and use virtualenv, putting them in the strange situation of having to do that because then they can activate the virtual env by using the Unix shell-specific `source` builtin instead of using native scripts activate.bat or activate.ps1

I think (tm) this is not the same for django-admin.exe which afaik supports venvs (in the sense that it will choose the venv python over the default installed python -- do not ask me how and I might also be wrong here).
 

Another change proposed by the PR is the addition of a custom Sphinx directive that modifies the UI of CLI example text boxes so they can show a native prompt and native command line input as it should actually be typed by the user either on Unix-based shells or the Windows command prompt through a tabbed interface.

+ 0/1 -- I'll happily merge but I do not care enough about windows to push it forward.

Cheers,
Florian

[Kevin Christopher Henry]

Regarding venv and bash, I filed a ticket [1] three years ago to have the bash script included with the Windows venv installation, and it looks like that change is in from 3.5 on. So in any case we shouldn't need to suggest virtualenv any more.

Although I personally use bash, I definitely agree that it would nice to have a Windows-native solution that Just Works, so +1 from this occasional Windows user.

Cheers,
Kevin

[1] https://bugs.python.org/issue22343