Os.listdir: примеры (PYTHON)

Простые примеры применения

Пример 1: Вывод содержимого текущей директории.

import os
items = os.listdir()
print(items)

['folder1', 'main.py', 'data.txt', 'config.json']

Пример 2: Получение списка в указанном каталоге с помощью строкового пути.

import os
path = "/home/user/documents"
try:
    items = os.listdir(path)
    print(items)
except FileNotFoundError:
    print(f"Директория {path} не найдена")

['report.pdf', 'notes', 'photo.jpg']

Пример 3: Использование байтового пути (актуально для файловых систем, где имена не в кодировке Unicode).

import os
byte_path = b"/home/user/documents"
items = os.listdir(byte_path)
print(items)

[b'report.pdf', b'notes', b'photo.jpg']

Похожие функции в Python

os.scandir(): Возвращает итератор объектов os.DirEntry. Эти объекты содержат не только имя, но и дополнительную информацию (тип файла, атрибуты) без дополнительных системных вызовов. Эффективнее для обхода больших директорий.

pathlib.Path.iterdir(): Часть модуля pathlib (доступен с Python 3.4). Возвращает итератор объектов Path, что удобно для современного объектно-ориентированного подхода к работе с путями.

glob.glob(): Позволяет получать список путей, соответствующих заданному шаблону (например, *.txt). Полезно для фильтрации файлов по расширению или имени.

Выбор функции зависит от задачи: os.listdir хорош для простого получения списка имен, os.scandir - для производительности и получения метаданных, pathlib - для современного кода, glob - для фильтрации по шаблону.

Аналоги в других языках программирования

PHP: scandir($directory). Возвращает массив имен файлов и директорий, включает '.' и '..'.

$items = scandir("/path/to/dir");
print_r($items);

Array
(
    [0] => .
    [1] => ..
    [2] => file.txt
    [3] => folder
)

JavaScript (Node.js): fs.readdirSync(path) (синхронная версия).

const fs = require('fs');
const items = fs.readdirSync("./");
console.log(items);

[ 'app.js', 'node_modules', 'package.json' ]

Java: File.list() или Files.list(Path dir) (NIO2 API).

File dir = new File("/path");
String[] items = dir.list();
System.out.println(Arrays.toString(items));

C#: Directory.GetFiles(path) (только файлы) или Directory.GetFileSystemEntries(path) (файлы и папки).

string[] items = Directory.GetFileSystemEntries(@"C:\MyDir");
Console.WriteLine(String.Join(", ", items));

Golang: ioutil.ReadDir(dirname) (устарело) или os.ReadDir(name) (с Go 1.16). Возвращает срезы os.DirEntry или fs.DirEntry.

items, err := os.ReadDir(".")
if err != nil { log.Fatal(err) }
for _, item := range items {
    fmt.Println(item.Name())
}

Основное отличие от Python - частое включение специальных записей . и .. и разные подходы к обработке ошибок и возвращаемым типам данных (итераторы, массивы, срезы).

Распространенные ошибки

1. FileNotFoundError: Возникает при указании несуществующего пути.

import os
try:
    os.listdir("/nonexistent/path")
except FileNotFoundError as e:
    print(f"Ошибка: {e}")

Ошибка: [Errno 2] No such file or directory: '/nonexistent/path'

2. NotADirectoryError: Если переданный путь ведет к файлу, а не к директории.

import os
open('dummy.txt', 'w').close()
try:
    os.listdir('dummy.txt')
except NotADirectoryError as e:
    print(f"Ошибка: {e}")

Ошибка: [Errno 20] Not a directory: 'dummy.txt'

3. PermissionError: Отсутствие прав на чтение указанной директории.

import os
try:
    os.listdir("/root")
except PermissionError as e:
    print(f"Ошибка доступа: {e}")

Ошибка доступа: [Errno 13] Permission denied: '/root'

4. Путаница между путем и результатом: Функция возвращает только имена, а не полные пути. Для работы с файлами часто нужен полный путь, который можно получить с помощью os.path.join().

import os
folder = "my_folder"
for name in os.listdir(folder):
    full_path = os.path.join(folder, name)
    print(full_path)

my_folder/file1.txt
my_folder/subdir

Изменения в последних версиях Python

В Python 3.2 функция os.listdir() получила поддержку специального аргумента dir_fd, позволяющего указывать дескриптор открытой директории (для операций относительно него). Однако для listdir этот параметр не был реализован.

Основные изменения связаны с обработкой байтовых путей и файловых систем, не поддерживающих Unicode. Поведение функции стабильно на протяжении многих версий.

Важным контекстным изменением стало появление в Python 3.5 более производительной альтернативы - os.scandir(), которая позже легла в основу высокоуровневого обхода директорий.

Также начиная с Python 3.4, рекомендуется использовать объектно-ориентированный API модуля pathlib для новых проектов, хотя os.listdir() сохраняет полную поддержку и обратную совместимость.

Расширенные примеры использования

Пример 1: Фильтрация только файлов (исключая подкаталоги).

import os
path = "."
items = os.listdir(path)
files_only = [item for item in items if os.path.isfile(os.path.join(path, item))]
print(f"Файлы: {files_only}")

Файлы: ['main.py', 'data.txt', 'config.json']

Пример 2: Получение списка с сортировкой по дате изменения.

import os
path = "."
items = os.listdir(path)
items_with_mtime = [(item, os.path.getmtime(os.path.join(path, item))) for item in items]
sorted_items = sorted(items_with_mtime, key=lambda x: x[1], reverse=True)
print("Сортировка по дате изменения (сначала новые):")
for name, mtime in sorted_items:
    print(f"  {name} - {mtime}")

Сортировка по дате изменения (сначала новые):
  config.json - 1678886400.5
  main.py - 1678886300.2
  data.txt - 1678886200.8
  folder1 - 1678886100.1

Пример 3: Рекурсивный обход всех поддиректорий с помощью os.listdir.

import os
def list_all(path):
    for entry in os.listdir(path):
        full_path = os.path.join(path, entry)
        print(full_path)
        if os.path.isdir(full_path):
            list_all(full_path)

list_all(".")

./main.py
./data.txt
./config.json
./folder1
./folder1/subfile.txt
./folder1/another.pdf

Пример 4: Использование с кодировками на Windows для работы с путями, содержащими не-ASCII символы.

import os
import sys
# На Windows может потребоваться указать кодировку для файловой системы
if sys.platform == "win32":
    path = "тестовая_папка"
    # Создаем папку для примера
    if not os.path.exists(path):
        os.mkdir(path)
    items = os.listdir(path)
    print(f"Содержимое папки с русским названием: {items}")

Содержимое папки с русским названием: []

Пример 5: Сравнение производительности разных методов получения списка файлов.

import os
import time
path = "/usr/bin"  # Большая директория для теста
start = time.time()
items_listdir = os.listdir(path)
time_listdir = time.time() - start
print(f"os.listdir: {len(items_listdir)} элементов, {time_listdir:.4f} сек.")

os.listdir: 2560 элементов, 0.0008 сек.