2016-08-23 8 views
0

명명 된 튜플을 사용하여 여러 함수를 통과하는 여러 변수를 유지하면서 일부 코드를 정리하려고합니다. 다음은 간단한 예입니다 (실제로 몇 가지 추가 인수가 있습니다).명명 된 튜플을 문서화하는 표준 방법은 무엇입니까?

하기 전에 :

def my_function(session_cass, session_solr, session_mysql, some_var, another): 
"""Blah blah. 

Args: 
    session_cass (Session): Cassandra session to execute queries with. 
    session_solr (SolrConnection): Solr connection to execute requests with. 
    session_mysql (connection): MySQL connection to execute queries with. 
    some_var (str): Yada yada. 
    another (int): Yada yada. 
""" 

후 : 문서화 문자열에 대한

def my_function(sessions, some_var, another): 
"""Blah blah. 

Args: 
    sessions (namedtuple): Holds all the database sessions. 
    some_var (str): Yada yada. 
    another (int): Yada yada. 
""" 

, 나는 (this post에서 영감) 유형의 추가와 함께, 구글 스타일 가이드 다음 봤는데 어떤 정말 좋아 어떤 형식이 들어오는 지 추적하는 것이 훨씬 쉽기 때문입니다.

제 질문은이 시나리오에서 명명 된 튜플을 문서화하는 방법에 대해 설명하겠습니까? 분명히 현재 설정되어 있기 때문에 명명 된 튜플 내의 유형에 대한 정보가 없습니다. 여기에 문서화 문자열을 확장하거나 정의 된 곳에 이름이 붙은 파일을 문서화하는 방법이 있습니까?

나는이 매너에 클래스를 문서화 할 수 있지만 변수를 보유하는 것 이외에 다른 목적을 가지고 있지 않기 때문에 클래스를 사용하지 않으려 고합니다.

+1

왜 명명 된 튜플인가? 왜 {ident : session}의 (임의의) 사전이나 심지어 세션 목록 만 가져 가면 안됩니다. 실제로 터플이라는 이름의 튜플이 리턴 된 값보다 훨씬 더 잘 작동한다는 것을 검증하고 있습니까? 메서드 인수) –

+0

특별한 이유는 없습니다. 나는 둘 다 고려하고 임의적으로 namedtuple을 선택했다 - 더 "가벼운"것처럼 보였고 일반적으로 값이 모두 같은 유형 (예 : 유형을 혼합 할 수 있음을 알고 있음) 인 경우 사전을 사용합니다. 어쨌든, 저는이 질문이 두 가지 모두 동일하다고 생각합니다 - 좀 더 일반적인 의미에서 함수에 전달할 때 혼합 유형을 포함 할 때이를 문서화하는 가장 좋은 방법은 무엇입니까? 아마도 클래스를 사용하는 것이 더 좋을 수도 있고 (클래스 문서에서 타입을 문서화하는 것), 또는 그것에 대해 걱정하지 않고 namedtuple/dictionary가 초기화 된 곳으로 역 추적 할 수도 있습니다. – latetojoin

답변

1

나는 구글 스타일 가이드에 익숙하지 않은,하지만 이것에 대해 방법 : namedtuple 또는 튜플 또는 목록 또는 무엇이든을위한

그게 내가 온이

def my_function(sessions, some_var, another): 
    """Blah blah. 

    Args: 
     sessions (sequence): A sequence of length n that 
          holds all the database sessions. 
          In position 0 need bla bla 
          In position 1 need ble ble 
          ... 
          In position n-1 need blu blu 
     some_var (str): Yada yada. 
     another (int): Yada yada. 
    """  

처럼 뭔가를 갈 것입니다 교환 할 수있다 반면 나는 어떻게

에 대한 namedtuple의 속성, 사전이

def my_function(sessions, some_var, another): 
    """Blah blah. 

    Args: 
     sessions (object): A object that holds all the database sessions. 
          It need the following attributes 
          bla_bla is ... 
          ble_ble is ... 
          ... 
          blu_blu is ... 
     some_var (str): Yada yada. 
     another (int): Yada yada. 
    """  

같은 어쩌면 무언가를 사용하는 경우 6,

def my_function(sessions, some_var, another): 
    """Blah blah. 

    Args: 
     sessions (map): A dictionary-like object that holds all the 
         database sessions, it need the following keys 
         bla_bla is ... 
         ble_ble is ... 
          ... 
         blu_blu is ... 
     some_var (str): Yada yada. 
     another (int): Yada yada. 
    """  

또는 각 인스턴스에서

def my_function(sessions, some_var, another): 
    """Blah blah. 

    Args: 
     sessions (customclass): Holds all the database sessions. 
     some_var (str): Yada yada. 
     another (int): Yada yada. 
    """ 

는 기능이 제대로 작동하는 데 필요한 최소한의 기능을 요청