nntplib --- NNTP 프로토콜 클라이언트¶
소스 코드: Lib/nntplib.py
이 모듈은 네트워크 뉴스 전송 프로토콜(Network News Transfer Protocol)의 클라이언트 측을 구현하는 클래스 NNTP를 정의합니다. 뉴스 리더나 포스터 또는 자동화된 뉴스 프로세서를 구현하는 데 사용할 수 있습니다. 이전 RFC 977과 RFC 2980뿐만 아니라 RFC 3977과 호환됩니다.
다음은 사용 방법에 대한 두 가지 작은 예입니다. 뉴스 그룹에 대한 일부 통계를 나열하고 최근 10개 기사의 제목(subject)을 인쇄하려면 이렇게 합니다:
>>> s = nntplib.NNTP('news.gmane.io')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
... print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'
바이너리 파일에서 기사를 게시하려면 (기사에 유효한 헤더가 있고 특정 뉴스 그룹에 게시할 권한이 있다고 가정합니다):
>>> s = nntplib.NNTP('news.gmane.io')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'
모듈 자체는 다음 클래스를 정의합니다:
-
class
nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])¶ port 포트에서 리스닝하면서 호스트 host에서 실행 중인 NNTP 서버에 대한 연결을 나타내는 새
NNTP객체를 반환합니다. 소켓 연결에 대한 선택적 timeout을 지정할 수 있습니다. 선택적 user와 password가 제공되거나,/.netrc에 적합한 자격 증명이 존재하고 선택적 플래그 usenetrc가 참이면,AUTHINFO USER와AUTHINFO PASS명령이 서버에 사용자를 식별하고 인증하는 데 사용됩니다. 선택적 플래그 readermode가 참이면, 인증이 수행되기 전에mode reader명령이 전송됩니다. 로컬 시스템의 NNTP 서버에 연결하고group과 같은 리더 특정 명령을 호출하려면 때때로 리더 모드가 필요합니다. 예기치 않은NNTPPermanentError가 발생하면, readermode를 설정해야 합니다.NNTP클래스는OSError예외를 조건 없이 소비하고 완료 시 NNTP 연결을 닫는with문을 지원합니다. 예를 들면:>>> from nntplib import NNTP >>> with NNTP('news.gmane.io') as n: ... n.group('gmane.comp.python.committers') ... ('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers') >>>
인자
self,host,port로 감사 이벤트nntplib.connect를 발생시킵니다.인자
self,line으로 감사 이벤트nntplib.putline을 발생시킵니다.버전 3.2에서 변경: usenetrc는 이제 기본적으로
False입니다.버전 3.3에서 변경:
with문에 대한 지원이 추가되었습니다.버전 3.9에서 변경: timeout 매개 변수가 0으로 설정되면, 비 블로킹 소켓이 만들어지지 않도록
ValueError가 발생합니다.
-
class
nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])¶ port 포트에서 리스닝하면서 host 호스트에서 실행 중인 NNTP 서버에 대한 암호화 된 연결을 나타내는 새
NNTP_SSL객체를 반환합니다.NNTP_SSL객체는NNTP객체와 같은 메서드를 갖습니다. port를 생략하면, 포트 563(NNTPS)이 사용됩니다. ssl_context도 선택적이며,SSLContext객체입니다. 모범 사례를 보려면 보안 고려 사항을 읽으십시오. 다른 모든 매개 변수는NNTP와 같게 작동합니다.SSL-on-563은 RFC 4642에 따라 권장되지 않고, 아래 설명된 STARTTLS로 대체합니다. 그러나, 일부 서버는 전자만 지원합니다.
인자
self,host,port로 감사 이벤트nntplib.connect를 발생시킵니다.인자
self,line으로 감사 이벤트nntplib.putline을 발생시킵니다.버전 3.2에 추가.
버전 3.4에서 변경: 이 클래스는 이제
ssl.SSLContext.check_hostname과 서버 이름 표시(Server Name Indication)(ssl.HAS_SNI를 참조하십시오)로 호스트명 확인을 지원합니다.버전 3.9에서 변경: timeout 매개 변수가 0으로 설정되면, 비 블로킹 소켓이 만들어지지 않도록
ValueError가 발생합니다.
-
exception
nntplib.NNTPError¶ 표준 예외
Exception에서 파생된 이 클래스는nntplib모듈이 발생시키는 모든 예외의 베이스 클래스입니다. 이 클래스의 인스턴스는 다음과 같은 어트리뷰트를 갖습니다:
-
exception
nntplib.NNTPReplyError¶ 서버에서 예기치 않은 응답이 수신될 때 발생하는 예외.
-
exception
nntplib.NNTPTemporaryError¶ 400--499 범위의 응답 코드가 수신될 때 발생하는 예외.
-
exception
nntplib.NNTPPermanentError¶ 500--599 범위의 응답 코드가 수신될 때 발생하는 예외.
-
exception
nntplib.NNTPProtocolError¶ 서버에서 1--5 범위의 숫자로 시작하지 않는 응답을 수신할 때 발생하는 예외.
-
exception
nntplib.NNTPDataError¶ 응답 데이터에 에러가 있을 때 발생하는 예외.
NNTP 객체¶
연결되었을 때, NNTP와 NNTP_SSL 객체는 다음과 같은 메서드와 어트리뷰트를 지원합니다.
어트리뷰트¶
메서드¶
거의 모든 메서드의 반환 튜플에서 첫 번째 항목으로 반환되는 response는 서버의 응답입니다: 3 자리 숫자 코드로 시작하는 문자열. 서버의 응답이 에러를 가리키면, 메서드는 위의 예외 중 하나를 발생시킵니다.
다음 메서드 중 다수는 선택적 키워드 전용 인자 file을 취합니다. file 인자가 제공될 때, 바이너리 쓰기를 위해 열린 파일 객체이거나, 기록될 디스크에 있는 파일의 이름이어야 합니다. 그러면 메서드는 서버가 반환한 모든 데이터를 (응답 줄과 종료 점을 제외하고) 파일에 기록합니다; 메서드가 일반적으로 반환하는 줄, 튜플 또는 객체의 리스트는 비어 있습니다.
버전 3.2에서 변경: 다음 메서드 중 많은 부분이 재작업 및 수정되어, 3.1과 호환되지 않습니다.
-
NNTP.quit()¶ QUIT명령을 전송하고 연결을 닫습니다. 일단, 이 메서드가 호출되면, NNTP 객체의 다른 메서드를 호출하면 안 됩니다.
-
NNTP.getwelcome()¶ 초기 연결에 대한 응답으로 서버에서 보낸 환영 메시지를 반환합니다. (이 메시지에는 때때로 사용자와 관련될 수 있는 고지 사항이나 도움말 정보가 포함되어 있습니다.)
-
NNTP.getcapabilities()¶ 서버가 광고한 RFC 3977 기능을 기능 이름을 값 리스트(비어있을 수 있습니다)로 매핑하는
dict인스턴스로 반환합니다.CAPABILITIES명령을 이해하지 못하는 레거시 서버에서는, 빈 딕셔너리가 대신 반환됩니다.>>> s = NNTP('news.gmane.io') >>> 'POST' in s.getcapabilities() True
버전 3.2에 추가.
-
NNTP.login(user=None, password=None, usenetrc=True)¶ 사용자 이름과 비밀번호로
AUTHINFO명령을 보냅니다. user와 password가None이고 usenetrc가 참이면 가능한 경우~/.netrc의 자격 증명이 사용됩니다.의도적으로 지연되지 않는 한, 일반적으로
NNTP객체 초기화 중에 로그인이 수행되며 별도로 이 함수를 호출할 필요가 없습니다. 인증을 강제로 지연시키려면, 객체를 만들 때 user나 password를 설정하지 말고, usenetrc를 False로 설정해야 합니다.버전 3.2에 추가.
-
NNTP.starttls(context=None)¶ STARTTLS명령을 보냅니다. 이것은 NNTP 연결에서 암호화를 활성화합니다. context 인자는 선택적이며ssl.SSLContext객체여야 합니다. 모범 사례를 보려면 보안 고려 사항을 읽으십시오.인증 정보가 전송된 후에는 이 작업이 수행되지 않을 수 있으며,
NNTP객체 초기화 중에 가능한 경우 기본적으로 인증이 수행됩니다. 이 동작을 억제하는 것에 대한 정보는NNTP.login()을 참조하십시오.버전 3.2에 추가.
버전 3.4에서 변경: 이 메서드는 이제
ssl.SSLContext.check_hostname과 서버 이름 표시(Server Name Indication)(ssl.HAS_SNI를 참조하십시오)로 호스트명 확인을 지원합니다.
-
NNTP.newgroups(date, *, file=None)¶ NEWGROUPS명령을 보냅니다. date 인자는datetime.date나datetime.datetime객체여야 합니다.(response, groups)쌍을 반환합니다. 여기서 groups는 지정된 date 이후의 새로운 그룹을 나타내는 리스트입니다. 그러나 file이 제공되면, groups는 비어 있습니다.>>> from datetime import date, timedelta >>> resp, groups = s.newgroups(date.today() - timedelta(days=3)) >>> len(groups) 85 >>> groups[0] GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')
-
NNTP.newnews(group, date, *, file=None)¶ NEWNEWS명령을 보냅니다. 여기서 group은 그룹 이름이나'*'이며, date는newgroups()에서와 같은 의미입니다.(response, articles)쌍을 반환합니다. 여기서 articles는 메시지 id의 리스트입니다.이 명령은 NNTP 서버 관리자가 자주 비활성화합니다.
-
NNTP.list(group_pattern=None, *, file=None)¶ LIST나LIST ACTIVE명령을 전송합니다. 쌍(response, list)를 반환합니다. 여기서 list는 이 NNTP 서버에서 사용 가능한 모든 그룹을 나타내는 튜플 리스트이며, 선택적으로 패턴 문자열 group_pattern과 일치합니다. 각 튜플의 형식은(group, last, first, flag)입니다. 여기서 group은 그룹 이름이고 last와 first는 마지막과 첫 번째 기사 번호이며, flag는 일반적으로 다음 값 중 하나를 취합니다:y: 로컬 게시물과 동료의 기사가 허용됩니다.m: 그룹이 조정되며 모든 게시가 승인되어야 합니다.n: 로컬 게시물이 허용되지 않으며, 동료의 기사만 허용됩니다.j: 동료의 기사가 대신 정크 그룹에 보관됩니다.x: 로컬 게시물이 없으며, 동료의 기사는 무시됩니다.=foo.bar: 기사가foo.bar그룹에 대신 보관됩니다.
flag에 다른 값이 있으면, 뉴스 그룹의 상태를 알 수 없는 것으로 간주해야 합니다.
이 명령은 특히 group_pattern이 지정되지 않으면 매우 큰 결과를 반환할 수 있습니다. 실제로 새로 고칠 필요가 없으면 결과를 오프라인으로 캐시 하는 것이 가장 좋습니다.
버전 3.2에서 변경: group_pattern이 추가되었습니다.
-
NNTP.descriptions(grouppattern)¶ grouppattern이 RFC 3977에 지정된 와일드 매트(wildmat) 문자열(DOS나 UNIX 셸 와일드카드 문자열과 본질적으로 동일합니다)인,
LIST NEWSGROUPS명령을 전송합니다.(response, descriptions)쌍을 반환합니다. 여기서 descriptions는 그룹 이름을 텍스트 설명에 매핑하는 딕셔너리입니다.>>> resp, descs = s.descriptions('gmane.comp.python.*') >>> len(descs) 295 >>> descs.popitem() ('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')
-
NNTP.description(group)¶ 단일 그룹 group에 대한 설명을 가져옵니다. 둘 이상의 그룹이 일치하면 ('group'이 실제 와일드 매트 문자열이면), 첫 번째 일치를 반환합니다. 일치하는 그룹이 없으면, 빈 문자열을 반환합니다.
이것은 서버에서 온 응답 코드를 제거합니다. 응답 코드가 필요하면,
descriptions()를 사용하십시오.
-
NNTP.group(name)¶ GROUP명령을 전송합니다. 여기서 name은 그룹 이름입니다. 존재하면, 그룹이 현재 그룹으로 선택됩니다. 튜플(response, count, first, last, name)을 반환합니다. 여기서 count는 그룹의 (추정된) 기사 수, first는 그룹의 첫 번째 기사 번호, last는 그룹의 마지막 기사 번호, name은 그룹 이름입니다.
-
NNTP.over(message_spec, *, file=None)¶ OVER명령이나 레거시 서버에서는XOVER명령을 보냅니다. message_spec은 메시지 id를 나타내는 문자열이거나, 현재 그룹의 기사 범위를 나타내는(first, last)튜플, 또는 현재 그룹의 first에서 마지막 기사까지의 기사 범위를 나타내는(first, None)튜플이거나, 또는 현재 그룹에서 현재 기사를 선택하는None입니다.쌍
(response, overviews)를 반환합니다. overviews는 message_spec으로 선택한 기사마다 하나씩(article_number, overview)튜플의 리스트입니다. 각 overview는 같은 수의 항목을 가진 딕셔너리이지만, 이 숫자는 서버에 따라 다릅니다. 이러한 항목은 메시지 헤더(키는 소문자 헤더 이름이 됩니다)나 메타 데이터 항목(키는":"이 앞에 붙은 메타 데이터 이름이 됩니다)입니다. 다음 항목은 NNTP 명세에 따라 제공됨이 보장됩니다:subject,from,date,message-id및references헤더:bytes메타 데이터: 전체 원본 아티클의 바이트 수 (헤더와 본문을 포함합니다):lines메타 데이터: 기사 본문의 줄 수
각 항목의 값은 문자열이거나, 존재하지 않으면
None입니다.비 ASCII 문자를 포함할 수 있는 헤더 값에
decode_header()함수를 사용하는 것이 좋습니다:>>> _, _, first, last, _ = s.group('gmane.comp.python.devel') >>> resp, overviews = s.over((last, last)) >>> art_num, over = overviews[0] >>> art_num 117216 >>> list(over.keys()) ['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject'] >>> over['from'] '=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>' >>> nntplib.decode_header(over['from']) '"Martin v. Löwis" <martin@v.loewis.de>'
버전 3.2에 추가.
-
NNTP.help(*, file=None)¶ HELP명령을 보냅니다. list가 도움말 문자열의 리스트인(response, list)쌍을 반환합니다.
-
NNTP.stat(message_spec=None)¶ STAT명령을 보냅니다. 여기서 message_spec은 메시지 id('<'과'>'로 감싼)이거나 현재 그룹의 기사 번호입니다. message_spec이 생략되거나None이면, 현재 그룹의 현재 기사가 고려됩니다. number가 기사 번호이고 id는 메시지 id인 트리플(response, number, id)를 반환합니다.>>> _, _, first, last, _ = s.group('gmane.comp.python.devel') >>> resp, number, message_id = s.stat(first) >>> number, message_id (9099, '<20030112190404.GE29873@epoch.metaslash.com>')
-
NNTP.article(message_spec=None, *, file=None)¶ ARTICLE명령을 보냅니다. 여기서 message_spec은stat()에서와 같은 의미입니다. 튜플(response, info)를 반환합니다. 여기서 info는 3개의 어트리뷰트 number, message_id 및 lines(순서대로)가 있는namedtuple입니다. number는 그룹의 기사 번호 (또는 정보가 없으면 0), message_id는 문자열 메시지 id, lines는 헤더와 본문을 포함하는 원시 메시지를 구성하는 (종료 줄 바꿈 없는) 줄의 리스트입니다.>>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>') >>> info.number 0 >>> info.message_id '<20030112190404.GE29873@epoch.metaslash.com>' >>> len(info.lines) 65 >>> info.lines[0] b'Path: main.gmane.org!not-for-mail' >>> info.lines[1] b'From: Neal Norwitz <neal@metaslash.com>' >>> info.lines[-3:] [b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']
-
NNTP.head(message_spec=None, *, file=None)¶ article()과 같지만,HEAD명령을 보냅니다. 반환된 (또는 file에 기록되는) lines는 본문이 아닌 메시지 헤더만 포함합니다.
-
NNTP.body(message_spec=None, *, file=None)¶ article()과 같지만,BODY명령을 보냅니다. 반환된 (또는 file에 기록되는) lines는 헤더가 아닌 메시지 본문만 포함합니다.
-
NNTP.post(data)¶ POST명령을 사용하여 기사를 게시합니다. data 인자는 바이너리 읽기를 위해 열린 파일 객체, 또는 바이트열 객체의 이터러블(게시할 기사의 원시 줄을 나타냅니다)입니다. 필수 헤더를 포함하여 올바르게 구성된 뉴스 기사를 나타내야 합니다.post()메서드는.으로 시작하는 줄을 자동으로 이스케이프하고 종료 줄을 추가합니다.메서드가 성공하면, 서버의 응답이 반환됩니다. 서버가 게시를 거부하면,
NNTPReplyError가 발생합니다.
-
NNTP.ihave(message_id, data)¶ IHAVE명령을 보냅니다. message_id는 서버로 보낼 메시지의 id입니다 ('<'과'>'로 감쌉니다). data 매개 변수와 반환 값은post()와 같습니다.
-
NNTP.slave()¶ SLAVE명령을 보냅니다. 서버의 응답을 반환합니다.
-
NNTP.set_debuglevel(level)¶ 인스턴스의 디버깅 수준을 설정합니다. 인쇄되는 디버깅 출력량을 제어합니다. 기본
0은 디버깅 출력을 생성하지 않습니다.1값은 요청이나 응답마다 한 줄씩 적당한 양의 디버깅 출력을 생성합니다.2이상의 값은 최대량의 디버깅 출력을 생성하여, 연결에서 주고받은 각 줄(메시지 텍스트를 포함합니다)을 로깅 합니다.
다음은 RFC 2980에 정의된 선택적 NNTP 확장입니다. 이 중 일부는 RFC 3977에서 새로운 명령으로 대체되었습니다.
-
NNTP.xhdr(hdr, str, *, file=None)¶ XHDR명령을 보냅니다. hdr 인자는 헤더 키워드입니다, 예를 들어'subject'. str 인자는'first-last'형식이어야 합니다. 여기서 first와 last는 검색할 첫 번째와 마지막 기사 번호입니다. 쌍(response, list)를 반환합니다. 여기서 list는 쌍(id, text)의 리스이고, id는 기사 번호(문자열)이고, text는 해당 기사에 대해 요청된 헤더의 텍스트입니다. file 매개 변수가 제공되면,XHDR명령의 출력이 파일에 저장됩니다. file이 문자열이면, 메서드는 해당 이름의 파일을 열고, 쓰고 나서 닫습니다. file이 파일 객체이면write()를 호출하여 명령 출력의 줄을 저장합니다. file이 제공되면, 반환된 list는 빈 리스트입니다.
유틸리티 함수¶
이 모듈은 다음과 같은 유틸리티 함수도 정의합니다:
-
nntplib.decode_header(header_str)¶ 모든 이스케이프 된 비 ASCII 문자를 역 이스케이프 하여, 헤더 값을 디코딩합니다. header_str은
str객체여야 합니다. 이스케이프 처리되지 않은 값이 반환됩니다. 사람이 읽을 수 있는 형식으로 일부 헤더를 표시하려면 이 함수를 사용하는 것이 좋습니다:>>> decode_header("Some subject") 'Some subject' >>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=") 'Débuter en Python' >>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=") 'Re: problème de matrice'