तेज़ दुश्मनी

tl; डॉ

github.com/QratorLabs/fastenum

pip install fast-enum 

एनम क्या हैं?

(यदि आपको लगता है कि आप जानते हैं कि - "मानक लाइब्रेरी में Enums" खंड तक स्क्रॉल करें)।

कल्पना करें कि आपको अपने डेटाबेस मॉडल में संस्थाओं के लिए सभी संभावित राज्यों के एक सेट का वर्णन करने की आवश्यकता है। आप संभवतः मॉड्यूल-स्तरीय विशेषताओं के रूप में परिभाषित स्थिरांक का एक गुच्छा उपयोग करेंगे:

 # /path/to/package/static.py: INITIAL = 0 PROCESSING = 1 PROCESSED = 2 DECLINED = 3 RETURNED = 4 ... 

... या वर्ग-स्तरीय विशेषताओं के रूप में उनकी अपनी कक्षा में परिभाषित:

 class MyModelStates: INITIAL = 0 PROCESSING = 1 PROCESSED = 2 DECLINED = 3 RETURNED = 4 

यह आपको उन राज्यों को उनके mnemonic नामों से संदर्भित करने में मदद करता है, जबकि वे आपके भंडारण में सरल पूर्णांक के रूप में बने रहते हैं। इसके द्वारा, आप अपने कोड के माध्यम से बिखरे हुए जादू की संख्या से छुटकारा पा लेते हैं और इसे अधिक पठनीय और आत्म-वर्णनात्मक बनाते हैं।

लेकिन, मॉड्यूल-स्तरीय स्थिरांक और स्थिर विशेषताओं वाले वर्ग दोनों अजगर वस्तुओं की अंतर्निहित प्रकृति से पीड़ित हैं: वे सभी परस्पर भिन्न हैं। हो सकता है कि आप गलती से रनटाइम पर अपने कॉन्स्टेंट को वैल्यू असाइन कर दें, और यह आपके टूटे हुए डीबग को डिबग और रोलबैक करने में गड़बड़ी है। इसलिए, आप स्थिरांक के अपने सेट को अपरिवर्तनीय बनाना चाहते हैं, जिसका अर्थ है कि दोनों स्थिरांक की संख्या और घोषित मूल्यों को रनटाइम पर संशोधित नहीं किया जाना चाहिए।

इस उद्देश्य के लिए आप उन्हें उदाहरण के रूप में नामित namedtuple() साथ namedtuple() में व्यवस्थित करने का प्रयास कर सकते हैं:

 MyModelStates = namedtuple('MyModelStates', ('INITIAL', 'PROCESSING', 'PROCESSED', 'DECLINED', 'RETURNED')) EntityStates = MyModelStates(0, 1, 2, 3, 4) 

हालाँकि, यह अभी भी बहुत समझ में नहीं आता है: इसके अलावा, namedtuple चीजें वास्तव में एक्स्टेंसिबल नहीं हैं। मान लीजिए कि आपके पास एक UI है जो इन सभी राज्यों को प्रदर्शित करता है। फिर आप अपने मॉड्यूल-आधारित स्थिरांक, विशेषताओं के साथ अपनी कक्षा या नामांकित टुपल्स का उपयोग कर सकते हैं उन्हें प्रस्तुत करने के लिए (अंतिम दो को प्रस्तुत करना आसान है, जबकि हम उस पर हैं)। लेकिन आपका कोड उपयोगकर्ता को आपके द्वारा परिभाषित प्रत्येक राज्य के लिए पर्याप्त विवरण देने के लिए कोई अवसर प्रदान नहीं करता है। इसके अलावा, यदि आप अपने यूआई में बहु-भाषा समर्थन और i18n को लागू करने की योजना बनाते हैं, तो आप पाएंगे कि इन विवरणों के लिए सभी अनुवादों को भरना एक अविश्वसनीय रूप से कठिन कार्य बन जाता है। मिलान वाले राज्य मानों में आवश्यक रूप से मिलान विवरण नहीं हो सकते हैं, जिसका अर्थ है कि आप अपने सभी INITIAL राज्यों को gettext में एक ही विवरण पर मैप नहीं कर सकते हैं। इसके बजाय, आपका स्थिरांक यह बन जाता है:

 INITIAL = (0, 'My_MODEL_INITIAL_STATE') 

आपकी कक्षा तब यह बन जाती है:

 class MyModelStates: INITIAL = (0, 'MY_MODEL_INITIAL_STATE') 

और अंत में, आपका नाम-पत्र namedtuple बन जाता है:

 EntityStates = MyModelStates((0, 'MY_MODEL_INITIAL_STATE'), ...) 

खैर, काफी अच्छा है, अब यह सुनिश्चित करता है कि आपके यूआई द्वारा समर्थित भाषाओं के लिए राज्य मूल्य और अनुवाद स्टब दोनों मैप किए गए हैं। लेकिन अब आप देख सकते हैं कि कोड जो उन मैपिंग का उपयोग करता है वह गड़बड़ हो गया है। जब भी आप अपनी इकाई के लिए एक मान निर्दिष्ट करने का प्रयास करते हैं, तो आपको अपने उपयोग की जाने वाली मैपिंग से इंडेक्स 0 पर मूल्य निकालने की भी ज़रूरत नहीं है:

 my_entity.state = INITIAL[0] 

या

 my_entity.state = MyModelStates.INITIAL[0] 

या

 my_entity.state = EntityStates.INITIAL[0] 

और इसी तरह। ध्यान रखें कि क्रमशः स्थिरांक और वर्ग विशेषताओं का उपयोग करने वाले पहले दो दृष्टिकोण, अभी भी उत्परिवर्तन से पीड़ित हैं।

और फिर एनम मंच पर आते हैं

 class MyEntityStates(Enum): def __init__(self, val, description): self.val = val self.description = description INITIAL = (0, 'MY_MODEL_INITIAL_STATE') PROCESSING = (1, 'MY_MODEL_BEING_PROCESSED_STATE') PROCESSED = (2, 'MY_MODEL_PROCESSED_STATE') DECLINED = (3, 'MY_MODEL_DECLINED_STATE') RETURNED = (4, 'MY_MODEL_RETURNED_STATE') 

यह बात है। अब आप आसानी से अपने रेंडरर (Jinja2 सिंटैक्स) में एनम को प्रसारित कर सकते हैं:

 {% for state in MyEntityState %} <option value=”{{ state.val }}”>{{ _(state.description) }}</option> {% endfor %} 

Enum दोनों सदस्य सेट के लिए अपरिवर्तनीय है (आप रनटाइम में एक नए सदस्य को परिभाषित नहीं कर सकते हैं, और न ही आप पहले से परिभाषित सदस्य को हटा सकते हैं) और वे सदस्य मान जो वे रखते हैं (आप किसी भी विशेषता मान को पुन: असाइन नहीं कर सकते हैं या कोई विशेषता नहीं हटा सकते हैं)।

अपने कोड में आप अपनी संस्थाओं को इस तरह से मान देते हैं:

 my_entity.state = MyEntityStates.INITIAL.val 

खैर, पर्याप्त स्पष्ट है। स्व वर्णनात्मक। काफी हद तक एक्स्टेंसिबल। यही हम Enums का उपयोग करते हैं।

यह तेज क्यों है?

लेकिन डिफ़ॉल्ट ENUM धीमा है, इसलिए हमने खुद से पूछा - क्या हम इसे और तेज़ बना सकते हैं?
जैसा कि यह पता चला है, हम कर सकते हैं। अर्थात्, इसे बनाना संभव है:

• सदस्य पहुंच पर 3 गुना तेज
• ~ 8.5 गुना तेजी से विशेषता ( name , value ) पहुंच पर
• मूल्य से MyEnum(value) पहुंच पर 3 गुना तेजी से ( MyEnum(value) की कक्षा MyEnum(value) पर कॉल)
• नाम से डेढ़ गुना तेजी से प्रवेश ( MyEnum[name] तरह MyEnum[name] )

पायथन में प्रकार और वस्तुएं गतिशील हैं। लेकिन पायथन में वस्तुओं की गतिशील प्रकृति को सीमित करने के उपकरण हैं। उनकी मदद से __slots__ का उपयोग __slots__ साथ-साथ डेटा __slots__ का उपयोग करने से बचें जहां महत्वपूर्ण जटिलता वृद्धि के बिना संभव हो या यदि आप गति में लाभ प्राप्त कर सकते हैं तो महत्वपूर्ण प्रदर्शन को बढ़ावा दे सकते हैं।

स्लॉट्स

उदाहरण के लिए, कोई __slots__ साथ वर्ग घोषणा का उपयोग कर सकता है - इस मामले में, कक्षा के उदाहरणों में केवल विशेषताओं का एक प्रतिबंधित समूह होगा: __slots__ में घोषित विशेषताएँ और माता-पिता वर्ग के सभी __slots__ ।

वर्णनकर्ता

डिफ़ॉल्ट रूप से अजगर दुभाषिया सीधे किसी वस्तु का गुण मान लौटाता है:

 value = my_obj.attribute # this is a direct access to the attribute value by the pointer that the object holds for that attribute 

पायथन डेटा मॉडल के अनुसार, यदि किसी ऑब्जेक्ट का गुण मान स्वयं एक ऑब्जेक्ट है जो डेटा डिस्क्रिप्टिव प्रोटोकॉल को लागू करता है, तो इसका मतलब है कि जब आप उस मूल्य को प्राप्त करने का प्रयास करते हैं, तो आपको पहले ऑब्जेक्ट के रूप में विशेषता मिलती है और फिर एक विशेष विधि __get__ है। कीपर ऑब्जेक्ट को पास करने वाले उस विशेषता-ऑब्जेक्ट को तर्क के रूप में कहा जाता है:

 obj_attribute = my_obj.attribute obj_attribute_value = obj_attribute.__get__(my_obj) 

मानक पुस्तकालय में Enums

मानक Enum कार्यान्वयन के कम से कम name और value विशेषताओं को types.DynamicClassAttribute रूप में घोषित किया types.DynamicClassAttribute । इसका मतलब है कि जब आप किसी सदस्य का name (या value ) प्राप्त करने का प्रयास करते हैं तो प्रवाह निम्न है:

 one_value = StdEnum.ONE.value # that is what you write in your code one_value_attribute = StdEnum.ONE.value one_value = one_value_attribute.__get__(StdEnum.ONE) 

 # and this is what really __get__ does (python 3.7 implementation): def __get__(self, instance, ownerclass=None): if instance is None: if self.__isabstractmethod__: return self raise AttributeError() elif self.fget is None: raise AttributeError("unreadable attribute") return self.fget(instance) 

 # since DynamicClassAttribute is a decorator on Enum methods `name` and `value` the final row of __get__() ends up with: @DynamicClassAttribute def name(self): """The name of the Enum member.""" return self._name_ @DynamicClassAttribute def value(self): """The value of the Enum member.""" return self._value_ 

तो, पूर्ण प्रवाह को निम्नलिखित छद्म कोड के रूप में दर्शाया जा सकता है:

 def get_func(enum_member, attrname): # this is also a __dict__ lookup so hash + hashtable scan also occur return getattr(enum_member, f'_{attrnme}_') def get_name_value(enum_member): name_descriptor = get_descriptor(enum_member, 'name') if enum_member is None: if name_descriptor.__isabstractmethod__: return name_descriptor raise AttributeError() elif name_descriptor.fget is None: raise AttributeError("unreadable attribute") return get_func(enum_member, 'name') 

हमने एक सरल स्क्रिप्ट बनाई है जो उपरोक्त निष्कर्ष को प्रदर्शित करती है:

 from enum import Enum class StdEnum(Enum): def __init__(self, value, description): self.v = value self.description = description A = 1, 'One' B = 2, 'Two' def get_name(): return StdEnum.A.name from pycallgraph import PyCallGraph from pycallgraph.output import GraphvizOutput graphviz = GraphvizOutput(output_file='stdenum.png') with PyCallGraph(output=graphviz): v = get_name() 

और हमने स्क्रिप्ट चलाने के बाद यह चित्र हमारे लिए बनाया:


यह साबित करता है कि हर बार जब आप stdlib enum के गुण name तक पहुँचते हैं और value लेते हैं कि यह एक डिस्क्रिप्टर कहलाता है। बदले में यह डिस्क्रिप्टर, डिस्क्रिप्टर के साथ सजे स्टैमलिब एनुम की डिफ def name(self) प्रॉपर्टी को कॉल करने के साथ समाप्त होता है।

खैर, आप हमारे FastEnum से इसकी तुलना कर सकते हैं:

 from fast_enum import FastEnum class MyNewEnum(metaclass=FastEnum): A = 1 B = 2 def get_name(): return MyNewEnum.A.name from pycallgraph import PyCallGraph from pycallgraph.output import GraphvizOutput graphviz = GraphvizOutput(output_file='fastenum.png') with PyCallGraph(output=graphviz): v = get_name() 

जो इस तस्वीर का आउटपुट देता है:


यही कारण है कि वास्तव में मानक Enum कार्यान्वयन के अंदर हर बार जब आप अपने Enum सदस्यों के name और value विशेषताओं का उपयोग करते हैं। और इसीलिए हमारा कार्यान्वयन तेज है।

पायम स्टैंडर्ड लाइब्रेरी के एनम वर्ग के कार्यान्वयन में वर्णक प्रोटोकॉल कॉल के टन का उपयोग किया जाता है। जब हमने अपनी परियोजनाओं में मानक एनम का उपयोग करने की कोशिश की है तो हमने देखा है कि Enum सदस्यों के name और value विशेषताओं के लिए कितने डिस्क्रिप्टर प्रोटोकॉल कॉल किए गए थे। और क्योंकि पूरे कोड में गणना का अत्यधिक उपयोग किया गया था, जिसके परिणामस्वरूप प्रदर्शन खराब था।

इसके अलावा, मानक एनम वर्ग में सहायक "संरक्षित" विशेषताओं के एक जोड़े होते हैं:

• _member_names_ - एक सूची जिसमें _member_names_ सदस्यों के सभी नाम हैं;
• _member_map_ - एक आदेश दिया गया है कि सदस्य के लिए एक enum सदस्य का नाम मैप करता है;
• _value2member_map_ - एक रिवर्स शब्दकोष जो _value2member_map_ सदस्यों के लिए enum सदस्य मानों को मैप करता है।

डिक्शनरी लुकअप धीमा है क्योंकि हर एक हैश कैलकुलेशन और हैश टेबल लुकअप की ओर जाता है, जो उन डिक्शनरी को एनम क्लास के लिए गैर-इष्टतम आधार संरचना बनाता है। यहां तक ​​कि सदस्य स्वयं भी पुनर्प्राप्ति करता है (जैसा कि StdEnum.MEMBER ) एक शब्दकोश खोज है।

हमारा रास्ता

अपने Enum कार्यान्वयन को विकसित करते समय, हमने उन सुंदर सी-भाषा enumerations और सुंदर एक्स्टेंसिबल Java Enums को ध्यान में रखा। हमारे कार्यान्वयन में मुख्य विशेषताएं जो हम चाहते थे:

• एक Enum जितना संभव हो उतना स्थिर होना चाहिए; "स्टैटिक" से हमारा तात्पर्य है: यदि किसी चीज़ की गणना एक बार और घोषणा के समय की जा सकती है, तो उसे करना चाहिए;
• यदि कोई उपवर्ग नई एनुम सदस्यों को परिभाषित करता है, तो एनम को उपवर्गित नहीं किया जाना चाहिए ("अंतिम" वर्ग) - यह मानक पुस्तकालय कार्यान्वयन के लिए सही है, इस अपवाद के साथ कि उप-वर्ग निषिद्ध है भले ही कोई नया सदस्य परिभाषित न हो;
• एक एनम में एक्सटेंशन (अतिरिक्त विशेषताओं, विधियों और इतने पर) के लिए विशाल संभावनाएं होनी चाहिए।

जब हम डिक्शनरी लुकअप का उपयोग करते हैं, तब केवल Enum सदस्य के लिए रिवर्स मैपिंग value होता है। अन्य सभी गणना कक्षा घोषणा के दौरान सिर्फ एक बार की जाती हैं (जहां प्रकार निर्माण को अनुकूलित करने के लिए मेटाकलास हुक का उपयोग किया जाता है)।
मानक पुस्तकालय कार्यान्वयन के विपरीत, हम प्रथम मान को सदस्य मूल्य के रूप में वर्ग घोषणा में = चिन्ह के बाद मानते हैं:
मानक पुस्तकालय में A = 1, 'One' पूरे टापल 1, "One" दर्शाता है 1, "One" को value रूप में माना जाता है
A: 'MyEnum' = 1, 'One' को हमारे कार्यान्वयन में केवल 1 माना जाता है

जब भी संभव हो __slots__ का उपयोग करके आगे की गति प्राप्त की जाती है। पायथन डेटा मॉडल वर्गों में __slots__ साथ घोषित __dict__ विशेषता नहीं __dict__ है जो इंस्टेंस गुण रखता है (इसलिए आप __slots__ में उल्लिखित किसी भी विशेषता को निर्दिष्ट नहीं कर सकते हैं)। इसके अतिरिक्त, __slots__ में परिभाषित विशेषताएँ सी-स्तर ऑब्जेक्ट पॉइंटर के लिए निरंतर ऑफ़सेट पर एक्सेस की जाती हैं। यह हाई-स्पीड विशेषता एक्सेस है क्योंकि यह हैश गणना और हैशटेबल स्कैन से बचता है।

अतिरिक्त भत्ते क्या हैं?

फास्टनम 3.6 से पहले पायथन के किसी भी संस्करण के साथ संगत नहीं है, क्योंकि यह typing मॉड्यूल का अत्यधिक उपयोग करता है जिसे पायथन 3.6 में पेश किया गया था; एक मान सकता है कि PyPI से एक बैकपोर्ट typing मॉड्यूल स्थापित करने से मदद मिलेगी। जवाब है: नहीं। कार्यान्वयन PEP-484 का उपयोग कुछ कार्यों और विधियों के तर्कों और रिटर्न वैल्यू टाइप हिंटिंग के लिए करता है, इसलिए पायथन 3.5 से पहले किसी भी संस्करण को सिंटैक्स असंगति के कारण समर्थित नहीं किया गया है। लेकिन फिर, __new__ के __new__ में कोड की बहुत पहली पंक्ति चर प्रकार संकेत के लिए PEP-526 वाक्यविन्यास का उपयोग करती है। तो पायथन 3.5 या तो ऐसा नहीं करेगा। पुराने संस्करणों में कार्यान्वयन को पोर्ट करना संभव है, हालांकि हम क्यूरेटर लैब्स में जब भी संभव हो तो टाइप हिंटिंग का उपयोग करते हैं क्योंकि यह बहुत महत्वपूर्ण प्रोजेक्ट विकसित करने में मदद करता है। और हे! आप 3.6 से पहले किसी भी अजगर से चिपकना नहीं चाहते हैं क्योंकि आपके मौजूदा कोड के साथ कोई पीछे की असंगतता नहीं है (यह मानते हुए कि आप पायथन 2 का उपयोग नहीं कर रहे हैं) हालांकि 3.5 की तुलना में asyncio में बहुत काम किया गया था।

बदले में, मानक पुस्तकालय के विपरीत auto अनावश्यक जैसे विशेष आयात करता है। आप अपने Enum वर्ग के नाम के साथ अपने सभी Enum सदस्यों को टाइप-हिंट करते हैं, जिससे कोई मूल्य नहीं मिलता है - और मूल्य आपके लिए स्वचालित रूप से उत्पन्न होगा। हालांकि अजगर 3.6 FastEnum के साथ काम करने के लिए पर्याप्त है, चेतावनी दी है कि घोषणा की गारंटी के मानक शब्दकोश आदेश केवल अजगर 3.7 में पेश किया गया था। हम किसी भी उपयोगी उपकरण को नहीं जानते हैं, जहां ऑटो-जनरेट वैल्यू ऑर्डर महत्वपूर्ण है (क्योंकि हम मानते हैं कि उत्पन्न मूल्य ही ऐसा मान नहीं है जो प्रोग्रामर ध्यान देता है)। फिर भी, अपने आप को चेतावनी दें कि क्या आप अभी भी अजगर 3.6 के साथ चिपके रहते हैं;

जिन लोगों को डिफॉल्ट 1 के बजाय 0 (शून्य) से शुरू होने की आवश्यकता होती है, वे एक विशेष _ZERO_VALUED डिक्लेरेशन विशेषता _ZERO_VALUED साथ ऐसा कर सकते हैं, यह विशेषता परिणामस्वरूप एनुम वर्ग से "मिटा" है;

हालांकि कुछ सीमाएँ हैं: सभी एनुम सदस्य के नामों की गणना की जानी चाहिए या उन्हें मेटाक्लस द्वारा नहीं लिया जाएगा और उन्हें एनम सदस्यों के रूप में नहीं माना जाएगा;

हालाँकि, आप अपने एनमों के लिए बेस क्लास की घोषणा कर सकते हैं (ध्यान रखें कि बेस क्लास एनम मेटाक्लास का उपयोग कर सकता है, इसलिए आपको सभी उपवर्गों को मेटाक्लस प्रदान करने की आवश्यकता नहीं है): आप इसमें सामान्य तर्क (गुण और विधियाँ) को परिभाषित कर सकते हैं। वर्ग, लेकिन एनम सदस्यों को परिभाषित नहीं कर सकता है (ताकि वर्ग "अंतिम रूप से" नहीं होगा)। आप तब उस वर्ग को बहुत सारी घोषणाओं में शामिल कर सकते हैं जो आप चाहते हैं और जो आपको सभी सामान्य तर्क प्रदान करेगा;

अन्य नाम। हम उन्हें एक अलग विषय में समझाएंगे (1.2.5 में लागू)

उपनाम और वे कैसे मदद कर सकते हैं

मान लीजिए कि आपके पास उपयोग करने वाला कोड है:

 package_a.some_lib_enum.MyEnum 

और यह कि MyEnum को इस तरह घोषित किया जाता है:

 class MyEnum(metaclass=FastEnum): ONE: 'MyEnum' TWO: 'MyEnum' 

अब, आपने कुछ रीफैक्टरिंग करने का निर्णय लिया और अपनी एनम को दूसरे पैकेज में ले जाना चाहते हैं। आप कुछ इस तरह से बनाएं:

 package_b.some_lib_enum.MyMovedEnum 

जहां MyMovedEnum को इस तरह घोषित किया गया है:

 class MyMovedEnum(MyEnum): pass 

अब। आप अपने कोड का उपयोग करने वाले सभी कोड के लिए "पदावनति" चरण शुरू करने के लिए तैयार हैं। आप MyEnum का उपयोग करने के लिए MyMovedEnum प्रत्यक्ष usages को MyEnum करते हैं (बाद में इसके सभी सदस्यों को MyEnum में MyEnum किया जाता है)। आप अपने प्रोजेक्ट डॉक्स में बताते हैं कि MyEnum को हटा दिया गया है और भविष्य में किसी बिंदु पर कोड से हटा दिया जाएगा। उदाहरण के लिए, अगली रिलीज़ में। अपने कोड पर विचार करें कि अचार के उपयोग से एनम विशेषताओं के साथ अपनी वस्तुओं को बचाता है। इस बिंदु पर, आप अपने कोड में MyMovedEnum का उपयोग करते हैं, लेकिन आंतरिक रूप से आपके सभी enum सदस्य अभी भी MyEnum उदाहरण हैं। आपका अगला कदम MyEnum और MyMovedEnum की घोषणाओं को स्वैप करना होगा ताकि MyMovedEnum अब MyMovedEnum का उपवर्ग न MyEnum और अपने सभी सदस्यों की घोषणा स्वयं कर सके; दूसरी ओर, MyEnum किसी भी सदस्य की घोषणा नहीं करेगा, लेकिन MyMovedEnum का केवल एक उपनाम (उपवर्ग) बन MyMovedEnum ।

और यह निष्कर्ष निकालता है। अनपिकल स्टेज पर अपने रनटाइम के रीस्टार्ट होने पर आपके सभी एनम वैल्यू को MyMovedEnum में री-रूट कर दिया MyMovedEnum और उस नए वर्ग के लिए फिर से बाउंड हो जाएगा। जिस क्षण आपको यकीन है कि आपके सभी चुने हुए ऑब्जेक्ट संयुक्त राष्ट्र (फिर से) इस वर्ग संगठन संरचना के साथ MyEnum हैं, आप एक नई रिलीज करने के लिए स्वतंत्र हैं, जहां पहले से चिह्नित किए गए के रूप में चिह्नित किया गया आपका MyEnum अप्रचलित घोषित किया जा सकता है और आपके कोडबेस से हटा MyEnum जा सकता है।

हम आपको इसे आजमाने के लिए प्रोत्साहित करते हैं! github.com/QratorLabs/fastenum , pypi.org/project/fast-enum । सभी क्रेडिट्स FastEnum लेखक santjagocorkez पर जाते हैं ।