site --- Móc cấu hình dành riêng cho trang web

Source code: Lib/site.py

This module is automatically imported during initialization. Việc nhập tự động có thể bị chặn bằng cách sử dụng tùy chọn -S của trình thông dịch.

Việc nhập mô-đun này thường gắn thêm các đường dẫn dành riêng cho trang web vào đường dẫn tìm kiếm mô-đun và thêm callables, bao gồm help() vào không gian tên tích hợp. Tuy nhiên, tùy chọn khởi động Python -S chặn điều này và mô-đun này có thể được nhập một cách an toàn mà không cần sửa đổi tự động đối với đường dẫn tìm kiếm mô-đun hoặc bổ sung vào nội trang. Để kích hoạt rõ ràng các bổ sung dành riêng cho trang web thông thường, hãy gọi hàm main().

Thay đổi trong phiên bản 3.3: Nhập mô-đun được sử dụng để kích hoạt thao tác đường dẫn ngay cả khi sử dụng -S.

Nó bắt đầu bằng cách xây dựng tối đa bốn thư mục từ phần đầu và phần đuôi. Đối với phần đầu, nó sử dụng sys.prefix và sys.exec_prefix; đầu trống được bỏ qua. Về phần đuôi thì dùng chuỗi rỗng rồi đến lib/site-packages (trên Windows) hoặc lib/pythonX.Y[t]/site-packages (trên Unix và macOS). (Hậu tố tùy chọn "t" biểu thị free-threaded build và được thêm vào nếu "t" có trong hằng số sys.abiflags.) Đối với mỗi kết hợp đầu-đuôi riêng biệt, nó sẽ xem liệu nó có đề cập đến một thư mục hiện có hay không và nếu có, hãy thêm nó vào sys.path và cũng kiểm tra đường dẫn mới được thêm vào cho các tệp cấu hình.

Thay đổi trong phiên bản 3.5: Hỗ trợ cho thư mục "site-python" đã bị xóa.

Thay đổi trong phiên bản 3.13: Trên Unix, các bản cài đặt Python Free threading được xác định bằng hậu tố "t" trong tên thư mục dành riêng cho phiên bản, chẳng hạn như lib/python3.13t/.

Thay đổi trong phiên bản 3.14: site không còn chịu trách nhiệm cập nhật sys.prefix và sys.exec_prefix trên Môi trường ảo nữa. Việc này hiện đã được thực hiện trong path initialization. Kết quả là, trong Môi trường ảo, sys.prefix và sys.exec_prefix không còn phụ thuộc vào việc khởi tạo site và do đó không bị ảnh hưởng bởi -S.

Khi chạy dưới virtual environment, tệp pyvenv.cfg trong sys.prefix được kiểm tra các cấu hình dành riêng cho trang web. Nếu khóa include-system-site-packages tồn tại và được đặt thành true (không phân biệt chữ hoa chữ thường), tiền tố cấp hệ thống sẽ được tìm kiếm cho các gói trang web, nếu không thì sẽ không tìm kiếm.

Tệp cấu hình đường dẫn là một tệp có tên có dạng name.pth và tồn tại ở một trong bốn thư mục được đề cập ở trên; nội dung của nó là các mục bổ sung (mỗi mục một dòng) sẽ được thêm vào sys.path. Các mục không tồn tại không bao giờ được thêm vào sys.path và không có kiểm tra nào được thực hiện rằng mục đó đề cập đến một thư mục chứ không phải một tệp. Không có mục nào được thêm vào sys.path nhiều lần. Các dòng trống và các dòng bắt đầu bằng # sẽ bị bỏ qua. Các dòng bắt đầu bằng import (theo sau là dấu cách hoặc tab) sẽ được thực thi.

Ghi chú

Một dòng thực thi trong tệp .pth được chạy mỗi lần khởi động Python, bất kể mô-đun cụ thể có thực sự được sử dụng hay không. Do đó, tác động của nó nên được giữ ở mức tối thiểu. Mục đích chính của các dòng thực thi là làm cho (các) mô-đun tương ứng có thể nhập được (tải móc nhập của bên thứ 3, điều chỉnh PATH, v.v.). Bất kỳ hoạt động khởi tạo nào khác đều phải được thực hiện khi nhập thực tế mô-đun, nếu và khi điều đó xảy ra. Việc giới hạn một đoạn mã trong một dòng duy nhất là một biện pháp có chủ ý để ngăn cản việc đặt bất kỳ thứ gì phức tạp hơn vào đây.

Thay đổi trong phiên bản 3.13: Các tệp .pth hiện được giải mã bởi UTF-8 lúc đầu và sau đó là locale encoding nếu nó không thành công.

Ví dụ: giả sử sys.prefix và sys.exec_prefix được đặt thành /usr/local. Thư viện Python X.Y sau đó được cài đặt trong /usr/local/lib/pythonX.Y. Giả sử thư mục này có thư mục con /usr/local/lib/pythonX.Y/site-packages với ba thư mục con là foo, bar và spam và hai tệp cấu hình đường dẫn, foo.pth và bar.pth. Giả sử foo.pth chứa những thứ sau:

cấu hình gói # foo

foo
thanh
vết bẩn

và bar.pth chứa:

cấu hình gói # bar

thanh

Sau đó, các thư mục dành riêng cho phiên bản sau sẽ được thêm vào sys.path, theo thứ tự sau:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

Lưu ý rằng bletch bị bỏ qua vì nó không tồn tại; thư mục bar đứng trước thư mục foo vì bar.pth xuất hiện trước foo.pth theo thứ tự bảng chữ cái; và spam bị bỏ qua vì nó không được đề cập trong tệp cấu hình đường dẫn.

sitecustomize

Sau những thao tác đường dẫn này, một nỗ lực được thực hiện để nhập một mô-đun có tên sitecustomize, mô-đun này có thể thực hiện các tùy chỉnh tùy ý dành riêng cho từng trang web. Nó thường được tạo bởi quản trị viên hệ thống trong thư mục gói trang web. Nếu quá trình nhập này không thành công với ImportError hoặc ngoại lệ lớp con của nó và thuộc tính name của ngoại lệ bằng 'sitecustomize' thì nó sẽ bị bỏ qua trong âm thầm. Nếu Python được khởi động mà không có sẵn luồng đầu ra, như với pythonw.exe trên Windows (được sử dụng theo mặc định để khởi động IDLE), thì đầu ra đã thử từ sitecustomize sẽ bị bỏ qua. Bất kỳ ngoại lệ nào khác đều gây ra sự thất bại thầm lặng và có lẽ là bí ẩn của quá trình.

usercustomize

Sau đó, một nỗ lực được thực hiện để nhập mô-đun có tên usercustomize, mô-đun này có thể thực hiện các tùy chỉnh tùy ý dành riêng cho người dùng, nếu ENABLE_USER_SITE là đúng. Tệp này dự định được tạo trong thư mục gói trang web của người dùng (xem bên dưới), là một phần của sys.path trừ khi bị -s tắt. Nếu quá trình nhập này không thành công với ImportError hoặc ngoại lệ lớp con của nó và thuộc tính name của ngoại lệ bằng 'usercustomize' thì nó sẽ bị bỏ qua trong âm thầm.

Lưu ý rằng đối với một số hệ thống không phải Unix, sys.prefix và sys.exec_prefix trống và các thao tác trên đường dẫn bị bỏ qua; tuy nhiên việc nhập sitecustomize và usercustomize vẫn được thử.

Cấu hình đường đọc

Trên các hệ thống hỗ trợ readline, mô-đun này cũng sẽ nhập và định cấu hình mô-đun rlcompleter, nếu Python được khởi động bằng interactive mode và không có tùy chọn -S. Hành vi mặc định là cho phép hoàn thành tab và sử dụng ~/.python_history làm tệp lưu lịch sử. Để tắt nó, hãy xóa (hoặc ghi đè) thuộc tính sys.__interactivehook__ trong mô-đun sitecustomize hoặc usercustomize hoặc tệp PYTHONSTARTUP của bạn.

Thay đổi trong phiên bản 3.4: Việc kích hoạt rlcompleter và lịch sử được thực hiện tự động.

Nội dung mô-đun

site.PREFIXES

Danh sách tiền tố cho các thư mục gói trang web.

site.ENABLE_USER_SITE

Cờ hiển thị trạng thái của thư mục gói trang web của người dùng. True có nghĩa là nó đã được kích hoạt và được thêm vào sys.path. False có nghĩa là nó đã bị vô hiệu hóa theo yêu cầu của người dùng (với -s hoặc PYTHONNOUSERSITE). None có nghĩa là nó đã bị vô hiệu hóa vì lý do bảo mật (không khớp giữa id người dùng hoặc nhóm và id hiệu dụng) hoặc bởi quản trị viên.

site.USER_SITE

Đường dẫn đến gói trang web của người dùng cho Python đang chạy. Có thể là None nếu getusersitepackages() chưa được gọi. Giá trị mặc định là ~/.local/lib/pythonX.Y[t]/site-packages cho các bản dựng macOS UNIX và không phải khung, ~/Library/Python/X.Y/lib/python/site-packages cho các bản dựng khung macOS và %APPDATA%\Python\PythonXY\site-packages trên Windows. Tùy chọn "t" biểu thị bản dựng có luồng tự do. Thư mục này là thư mục trang web, có nghĩa là các tệp .pth trong đó sẽ được xử lý.

site.USER_BASE

Đường dẫn đến thư mục cơ sở cho gói trang web của người dùng. Có thể là None nếu getuserbase() chưa được gọi. Giá trị mặc định là ~/.local cho các bản dựng không phải khung UNIX và macOS, ~/Library/Python/X.Y cho các bản dựng khung macOS và %APPDATA%\Python cho Windows. Giá trị này được sử dụng để tính toán các thư mục cài đặt cho tập lệnh, tệp dữ liệu, mô-đun Python, v.v. cho user installation scheme. Xem thêm PYTHONUSERBASE.

site.main()

Thêm tất cả các thư mục tiêu chuẩn dành riêng cho trang web vào đường dẫn tìm kiếm mô-đun. Hàm này được gọi tự động khi mô-đun này được nhập, trừ khi trình thông dịch Python được khởi động bằng cờ -S.

Thay đổi trong phiên bản 3.3: Hàm này từng được gọi vô điều kiện.

site.addsitedir(sitedir, known_paths=None)

Thêm một thư mục vào sys.path và xử lý các tệp .pth của nó. Thường được sử dụng trong sitecustomize hoặc usercustomize (xem ở trên).

site.getsitepackages()

Trả về danh sách chứa tất cả các thư mục gói trang web toàn cầu.

Added in version 3.2.

site.getuserbase()

Trả về đường dẫn của thư mục cơ sở người dùng, USER_BASE. Nếu nó chưa được khởi tạo, hàm này cũng sẽ thiết lập nó, tôn trọng PYTHONUSERBASE.

Added in version 3.2.

site.getusersitepackages()

Trả về đường dẫn của thư mục gói trang web dành riêng cho người dùng, USER_SITE. Nếu nó chưa được khởi tạo, hàm này cũng sẽ thiết lập nó, tôn trọng USER_BASE. Để xác định xem các gói trang web dành riêng cho người dùng đã được thêm vào sys.path hay chưa, nên sử dụng ENABLE_USER_SITE.

Added in version 3.2.

Giao diện dòng lệnh

Mô-đun site cũng cung cấp cách lấy thư mục người dùng từ dòng lệnh:

$ python -m trang web --trang web người dùng
/home/user/.local/lib/python3.11/site-packages

Nếu nó được gọi mà không có đối số, nó sẽ in nội dung của sys.path trên đầu ra tiêu chuẩn, tiếp theo là giá trị của USER_BASE và liệu thư mục có tồn tại hay không, sau đó điều tương tự với USER_SITE và cuối cùng là giá trị của ENABLE_USER_SITE.

--user-base

In đường dẫn đến thư mục cơ sở người dùng.

--user-site

In đường dẫn đến thư mục gói trang web của người dùng.

Nếu cả hai tùy chọn đều được đưa ra, cơ sở người dùng và trang người dùng sẽ được in (luôn theo thứ tự này), cách nhau bởi os.pathsep.

Nếu bất kỳ tùy chọn nào được đưa ra, tập lệnh sẽ thoát với một trong các giá trị sau: 0 nếu thư mục gói trang web của người dùng được bật, 1 nếu nó bị người dùng tắt, 2 nếu nó bị tắt vì lý do bảo mật hoặc bởi quản trị viên và giá trị lớn hơn 2 nếu có lỗi.

Xem thêm