email.utils: Các tiện ích khác

Source code: Lib/email/utils.py

Có một số tiện ích hữu ích được cung cấp trong mô-đun email.utils:

email.utils.localtime(dt=None)

Trả về giờ địa phương dưới dạng đối tượng datetime nhận biết được. Nếu được gọi mà không có đối số, hãy trả về thời gian hiện tại. Nếu không, đối số dt phải là một phiên bản datetime và nó được chuyển đổi sang múi giờ địa phương theo cơ sở dữ liệu múi giờ của hệ thống. Nếu dt là ngây thơ (nghĩa là dt.tzinfo là None), thì nó được coi là theo giờ địa phương.

Added in version 3.3.

Không được dùng nữa kể từ phiên bản 3.12, đã bị xóa trong phiên bản 3.14: Thông số isdst.

email.utils.make_msgid(idstring=None, domain=None)

Trả về một chuỗi phù hợp với tiêu đề Message-ID tương thích với RFC 2822-. idstring tùy chọn nếu được cung cấp, là một chuỗi được sử dụng để tăng cường tính duy nhất của id tin nhắn. domain tùy chọn nếu được cung cấp sẽ cung cấp phần msgid sau '@'. Mặc định là tên máy chủ cục bộ. It is not normally necessary to override this default, but may be useful certain cases, such as a constructing distributed system that uses a consistent domain name across multiple hosts.

Thay đổi trong phiên bản 3.2: Đã thêm từ khóa domain.

Các chức năng còn lại là một phần của email API cũ (Compat32). Không cần phải sử dụng trực tiếp những thứ này với API mới, vì việc phân tích cú pháp và định dạng mà chúng cung cấp được thực hiện tự động bởi bộ máy phân tích cú pháp tiêu đề của API mới.

email.utils.quote(str)

Trả về một chuỗi mới có dấu gạch chéo ngược trong str được thay thế bằng hai dấu gạch chéo ngược và dấu ngoặc kép được thay thế bằng dấu gạch chéo ngược kép.

email.utils.unquote(str)

Trả về một chuỗi mới là phiên bản unquoted của str. Nếu str kết thúc và bắt đầu bằng dấu ngoặc kép thì chúng sẽ bị loại bỏ. Tương tự như vậy, nếu str kết thúc và bắt đầu bằng dấu ngoặc nhọn, chúng sẽ bị loại bỏ.

email.utils.parseaddr(address, *, strict=True)

Địa chỉ phân tích cú pháp -- phải là giá trị của một số trường chứa địa chỉ, chẳng hạn như To hoặc Cc -- thành các phần cấu thành realname và email address. Trả về một bộ thông tin đó, trừ khi phân tích cú pháp không thành công, trong trường hợp đó sẽ trả về 2 bộ ('', '').

Nếu strict là đúng, hãy sử dụng trình phân tích cú pháp nghiêm ngặt để loại bỏ các đầu vào không đúng định dạng.

Thay đổi trong phiên bản 3.13: Thêm tham số tùy chọn strict và từ chối các đầu vào không đúng định dạng theo mặc định.

email.utils.formataddr(pair, charset='utf-8')

Nghịch đảo của parseaddr(), giá trị này lấy 2 bộ có dạng (realname, email_address) và trả về giá trị chuỗi phù hợp cho tiêu đề To hoặc Cc. Nếu phần tử đầu tiên của pair là sai thì phần tử thứ hai được trả về chưa sửa đổi.

charset tùy chọn là bộ ký tự sẽ được sử dụng trong mã hóa RFC 2047 của realname nếu realname chứa các ký tự không phải ASCII. Có thể là một phiên bản của str hoặc Charset. Mặc định là utf-8.

Thay đổi trong phiên bản 3.3: Đã thêm tùy chọn charset.

email.utils.getaddresses(fieldvalues, *, strict=True)

Phương thức này trả về danh sách 2 bộ dữ liệu có dạng được trả về bởi parseaddr(). fieldvalues là một chuỗi các giá trị trường tiêu đề có thể được trả về bởi Message.get_all.

Nếu strict là đúng, hãy sử dụng trình phân tích cú pháp nghiêm ngặt để loại bỏ các đầu vào không đúng định dạng.

Đây là một ví dụ đơn giản lấy tất cả người nhận tin nhắn:

từ email.utils nhập getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

Thay đổi trong phiên bản 3.13: Thêm tham số tùy chọn strict và từ chối các đầu vào không đúng định dạng theo mặc định.

email.utils.parsedate(date)

Cố gắng phân tích ngày theo quy tắc trong RFC 2822. tuy nhiên, một số người gửi thư không tuân theo định dạng đó như được chỉ định, vì vậy parsedate() cố gắng đoán chính xác trong những trường hợp như vậy. date là một chuỗi chứa ngày RFC 2822, chẳng hạn như "Mon, 20 Nov 1995 19:12:08 -0500". Nếu phân tích ngày thành công, parsedate() trả về 9 bộ dữ liệu có thể được chuyển trực tiếp tới time.mktime(); nếu không None sẽ được trả lại. Lưu ý rằng các chỉ mục 6, 7 và 8 của bộ kết quả không thể sử dụng được.

email.utils.parsedate_tz(date)

Thực hiện chức năng tương tự như parsedate(), nhưng trả về None hoặc 10 bộ; 9 phần tử đầu tiên tạo thành một bộ dữ liệu có thể được chuyển trực tiếp tới time.mktime() và phần tử thứ mười là phần bù của múi giờ của ngày từ UTC (là thuật ngữ chính thức cho Giờ chuẩn Greenwich) [1]. Nếu chuỗi đầu vào không có múi giờ, phần tử cuối cùng của bộ dữ liệu được trả về là 0, đại diện cho UTC. Lưu ý rằng các chỉ mục 6, 7 và 8 của bộ kết quả không thể sử dụng được.

email.utils.parsedate_to_datetime(date)

Nghịch đảo của format_datetime(). Thực hiện chức năng tương tự như parsedate(), nhưng nếu thành công sẽ trả về datetime; mặt khác, ValueError được tăng lên nếu date chứa giá trị không hợp lệ, chẳng hạn như một giờ lớn hơn 23 hoặc độ lệch múi giờ không nằm trong khoảng từ -24 đến 24 giờ. Nếu ngày đầu vào có múi giờ là -0000 thì datetime sẽ là datetime ngây thơ và nếu ngày tuân theo RFC thì ngày đó sẽ biểu thị thời gian trong UTC nhưng không có dấu hiệu nào về múi giờ nguồn thực tế của tin nhắn mà ngày đó xuất phát. Nếu ngày đầu vào có bất kỳ chênh lệch múi giờ hợp lệ nào khác thì datetime sẽ là datetime nhận biết được với timezone tzinfo tương ứng.

Added in version 3.3.

email.utils.mktime_tz(tuple)

Biến 10 bộ dữ liệu được parsedate_tz() trả về thành dấu thời gian UTC (giây kể từ Kỷ nguyên). Nếu mục múi giờ trong bộ dữ liệu là None, giả sử giờ địa phương.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

Trả về chuỗi ngày theo RFC 2822, ví dụ:

Thứ sáu, 09/11/2001 01:08:47 -0000

timeval tùy chọn nếu được cung cấp là giá trị thời gian dấu phẩy động được time.gmtime() và time.localtime() chấp nhận, nếu không thì thời gian hiện tại sẽ được sử dụng.

localtime tùy chọn là một cờ mà khi True diễn giải timeval và trả về một ngày tương ứng với múi giờ địa phương thay vì UTC, tính đến thời gian tiết kiệm ánh sáng ban ngày một cách chính xác. Mặc định là False nghĩa là UTC được sử dụng.

usegmt tùy chọn là cờ mà khi True xuất ra chuỗi ngày có múi giờ dưới dạng chuỗi ascii GMT, thay vì -0000 dạng số. Điều này là cần thiết cho một số giao thức (chẳng hạn như HTTP). Điều này chỉ áp dụng khi localtime là False. Mặc định là False.

email.utils.format_datetime(dt, usegmt=False)

Giống như formatdate, nhưng đầu vào là một phiên bản datetime. Nếu đó là một datetime đơn giản thì nó được coi là "UTC không có thông tin về múi giờ nguồn" và -0000 thông thường được sử dụng cho múi giờ. Nếu đó là datetime nhận biết được thì phần bù múi giờ bằng số sẽ được sử dụng. Nếu đó là múi giờ nhận biết có độ lệch bằng 0 thì usegmt có thể được đặt thành True, trong trường hợp đó, chuỗi GMT được sử dụng thay vì độ lệch múi giờ bằng số. Điều này cung cấp một cách để tạo tiêu đề ngày HTTP tuân thủ tiêu chuẩn.

Added in version 3.3.

email.utils.decode_rfc2231(s)

Giải mã chuỗi s theo RFC 2231.

email.utils.encode_rfc2231(s, charset=None, language=None)

Mã hóa chuỗi s theo RFC 2231. Tùy chọn charset và language, nếu được cung cấp là tên bộ ký tự và tên ngôn ngữ sẽ sử dụng. Nếu không được cung cấp, s sẽ được trả về nguyên trạng. Nếu charset được cung cấp nhưng language thì không, chuỗi được mã hóa bằng chuỗi trống cho language.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

Khi tham số tiêu đề được mã hóa ở định dạng RFC 2231, Message.get_param có thể trả về bộ 3 chứa bộ ký tự, ngôn ngữ và giá trị. collapse_rfc2231_value() biến chuỗi này thành chuỗi unicode. errors tùy chọn được chuyển tới đối số errors của phương thức encode() của str; nó mặc định là 'replace'. fallback_charset tùy chọn chỉ định bộ ký tự sẽ sử dụng nếu bộ ký tự trong tiêu đề RFC 2231 không được Python biết; nó mặc định là 'us-ascii'.

Để thuận tiện, nếu value được chuyển đến collapse_rfc2231_value() không phải là một bộ, thì nó phải là một chuỗi và được trả về không có trích dẫn.

email.utils.decode_params(params)

Giải mã danh sách thông số theo RFC 2231. params là một chuỗi gồm 2 bộ chứa các phần tử có dạng (content-type, string-value).

Chú thích cuối trang