Fixed #29983 -- Replaced os.path() with pathlib.Path in project template and docs.

Thanks Curtis Maloney for the original patch.

django/conf/project_template/project_name/settings.py-tpl

@@ -10,10 +10,10 @@ For the full list of settings and their values, see
 https://docs.djangoproject.com/en/{{ docs_version }}/ref/settings/
 """
 
-import os
+from pathlib import Path
 
-# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
-BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve(strict=True).parents[1]
 
 
 # Quick-start development settings - unsuitable for production
@@ -76,7 +76,7 @@ WSGI_APPLICATION = '{{ project_name }}.wsgi.application'
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.sqlite3',
-        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
+        'NAME': BASE_DIR / 'db.sqlite3',
     }
 }
 

docs/howto/overriding-templates.txt

@@ -27,9 +27,9 @@ Let's say you're trying to override the templates for a third-party application
 called ``blog``, which provides the templates ``blog/post.html`` and
 ``blog/list.html``. The relevant settings for your project would look like::
 
-    import os
+    from pathlib import Path
 
-    BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    BASE_DIR = Path(__file__).resolve(strict=True).parents[1]
 
     INSTALLED_APPS = [
         ...,
@@ -40,7 +40,7 @@ called ``blog``, which provides the templates ``blog/post.html`` and
     TEMPLATES = [
         {
             'BACKEND': 'django.template.backends.django.DjangoTemplates',
-            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'DIRS': [BASE_DIR / 'templates'],
             'APP_DIRS': True,
             ...
         },

docs/howto/static-files/index.txt

@@ -52,7 +52,7 @@ you can define a list of directories (:setting:`STATICFILES_DIRS`) in your
 settings file where Django will also look for static files. For example::
 
     STATICFILES_DIRS = [
-        os.path.join(BASE_DIR, "static"),
+        BASE_DIR / "static",
         '/var/www/static/',
     ]
 

docs/intro/tutorial02.txt

@@ -34,8 +34,8 @@ settings:
 * :setting:`NAME` -- The name of your database. If you're using SQLite, the
   database will be a file on your computer; in that case, :setting:`NAME`
   should be the full absolute path, including filename, of that file. The
-  default value, ``os.path.join(BASE_DIR, 'db.sqlite3')``, will store the file
-  in your project directory.
+  default value, ``BASE_DIR / 'db.sqlite3'``, will store the file in your
+  project directory.
 
 If you are not using SQLite as your database, additional settings such as
 :setting:`USER`, :setting:`PASSWORD`, and :setting:`HOST` must be added.

docs/intro/tutorial07.txt

@@ -306,7 +306,7 @@ Open your settings file (:file:`mysite/settings.py`, remember) and add a
     TEMPLATES = [
         {
             'BACKEND': 'django.template.backends.django.DjangoTemplates',
-            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'DIRS': [BASE_DIR / 'templates'],
             'APP_DIRS': True,
             'OPTIONS': {
                 'context_processors': [

docs/ref/contrib/gis/tutorial.txt

@@ -320,14 +320,12 @@ First, invoke the Django shell:
 
     $ python manage.py shell
 
-If you downloaded the :ref:`worldborders` data earlier in the
-tutorial, then you can determine its path using Python's built-in
-``os`` module::
+If you downloaded the :ref:`worldborders` data earlier in the tutorial, then
+you can determine its path using Python's :class:`pathlib.Path`::
 
-    >>> import os
+    >>> from pathlib import Path
     >>> import world
-    >>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__),
-    ...                             'data', 'TM_WORLD_BORDERS-0.3.shp'))
+    >>> world_shp = Path(world.__file__).resolve().parent / 'data' / 'TM_WORLD_BORDERS-0.3.shp'
 
 Now, open the world borders shapefile using GeoDjango's
 :class:`~django.contrib.gis.gdal.DataSource` interface::
@@ -433,7 +431,7 @@ To import the data, use a LayerMapping in a Python script.
 Create a file called ``load.py`` inside the ``world`` application,
 with the following code::
 
-    import os
+    from pathlib import Path
     from django.contrib.gis.utils import LayerMapping
     from .models import WorldBorder
 
@@ -452,9 +450,7 @@ with the following code::
         'mpoly' : 'MULTIPOLYGON',
     }
 
-    world_shp = os.path.abspath(
-        os.path.join(os.path.dirname(__file__), 'data', 'TM_WORLD_BORDERS-0.3.shp'),
-    )
+    world_shp = Path(__file__).resolve().parent / 'data' / 'TM_WORLD_BORDERS-0.3.shp'
 
     def run(verbose=True):
         lm = LayerMapping(WorldBorder, world_shp, world_mapping, transform=False)

docs/ref/templates/api.txt

@@ -831,7 +831,7 @@ loaders that come with Django:
 
         TEMPLATES = [{
             'BACKEND': 'django.template.backends.django.DjangoTemplates',
-            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'DIRS': [BASE_DIR / 'templates'],
         }]
 
     You can also override ``'DIRS'`` and specify specific directories for a
@@ -843,7 +843,7 @@ loaders that come with Django:
                 'loaders': [
                     (
                         'django.template.loaders.filesystem.Loader',
-                        [os.path.join(BASE_DIR, 'templates')],
+                        [BASE_DIR / 'templates'],
                     ),
                 ],
             },
@@ -917,7 +917,7 @@ loaders that come with Django:
 
         TEMPLATES = [{
             'BACKEND': 'django.template.backends.django.DjangoTemplates',
-            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'DIRS': [BASE_DIR / 'templates'],
             'OPTIONS': {
                 'loaders': [
                     ('django.template.loaders.cached.Loader', [

docs/releases/3.1.txt

@@ -232,6 +232,10 @@ Miscellaneous
 * The SQLite backend now supports :class:`pathlib.Path` for the ``NAME``
   setting.
 
+* The ``settings.py`` generated by the :djadmin:`startproject` command now uses
+  :class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
+  paths.
+
 .. _backwards-incompatible-3.1:
 
 Backwards incompatible changes in 3.1