Python 3.7 - struct

संरचना - बाइट डेटा के रूप में बाइट्स की व्याख्या




python

संरचना - बाइट डेटा के रूप में बाइट्स की व्याख्या

स्रोत कोड: Lib/struct.py

यह मॉड्यूल पायथन मूल्यों और सी संरचनाओं के बीच रूपांतरण करता है जिसे पायथन bytes ऑब्जेक्ट के रूप में दर्शाया गया है। इसका उपयोग फ़ाइलों में संग्रहीत बाइनरी डेटा या नेटवर्क कनेक्शन से अन्य स्रोतों के बीच निपटने में किया जा सकता है। यह सी स्ट्रिंग्स के लेआउट का संक्षिप्त विवरण और पायथन मूल्यों से / के लिए इच्छित रूपांतरण के रूप में प्रारूप स्ट्रिंग्स का उपयोग करता है।

ध्यान दें

डिफ़ॉल्ट रूप से, किसी दिए गए C संरचना को पैक करने के परिणाम में पैड बाइट्स शामिल होते हैं ताकि सी प्रकार के लिए उचित संरेखण बनाए रखा जा सके; इसी तरह, संरेखण को खोलते समय ध्यान में रखा जाता है। यह व्यवहार इसलिए चुना जाता है कि एक पैक किए गए संरचना के बाइट्स संगत C संरचना की स्मृति में लेआउट के बिल्कुल अनुरूप होते हैं। प्लेटफ़ॉर्म-स्वतंत्र डेटा स्वरूपों या अंतर्निहित पैड बाइट्स को हटाने के लिए, native आकार और संरेखण के बजाय standard आकार और संरेखण का उपयोग करें: विवरण के लिए बाइट ऑर्डर, आकार और संरेखण देखें।

कई struct कार्य (और struct तरीके) एक बफर तर्क लेते हैं। यह उन वस्तुओं को संदर्भित करता है जो बफर प्रोटोकॉल को लागू करते हैं और या तो पठनीय या पढ़ने योग्य लिखने योग्य बफर प्रदान करते हैं। उस उद्देश्य के लिए उपयोग किए जाने वाले सबसे आम प्रकार bytes और bytearray , लेकिन कई अन्य प्रकार जो बाइट्स के एक सरणी के रूप में देखे जा सकते हैं, बफर प्रोटोकॉल को लागू करते हैं, ताकि उन्हें bytes ऑब्जेक्ट से अतिरिक्त कॉपी किए बिना पढ़ा / भरा जा सके।

कार्य और अपवाद

मॉड्यूल निम्नलिखित अपवाद और कार्यों को परिभाषित करता है:

exception struct.error

विभिन्न अवसरों पर उठाया गया अपवाद; तर्क एक स्ट्रिंग है जो वर्णन करता है कि क्या गलत है।

struct.pack(format, v1, v2, ...)

मानों v1 , v2 ,… युक्त एक बाइट ऑब्जेक्ट लौटाएँ, जो प्रारूप स्ट्रिंग प्रारूप के अनुसार पैक किया गया है। तर्कों को प्रारूप द्वारा आवश्यक मूल्यों से बिल्कुल मेल खाना चाहिए।

struct.pack_into(format, buffer, offset, v1, v2, ...)

मान स्ट्रिंग v प्रारूप में मानों v1 , v2 , को पैक करें और स्थिति ऑफसेट पर शुरू होने वाले लेखन बफर बफर में पैक बाइट्स लिखें। ध्यान दें कि ऑफसेट एक आवश्यक तर्क है।

struct.unpack(format, buffer)

बफ़र बफ़र से अनपैक करें (संभवतः पैक स्ट्रिंग pack(format, ...) द्वारा प्रारूप स्ट्रिंग के प्रारूप के अनुसार। परिणाम एक टपल है, भले ही इसमें एक आइटम शामिल हो। बाइट्स में बफ़र के आकार को प्रारूप द्वारा आवश्यक आकार से मेल खाना चाहिए, जैसा कि calcsize() द्वारा परिलक्षित होता है।

struct.unpack_from(format, buffer, offset=0)

स्थिति स्ट्रिंग से शुरू होने वाले बफर से अनपैक करें, स्ट्रिंग स्ट्रिंग प्रारूप के अनुसार। परिणाम एक टपल है, भले ही इसमें एक आइटम शामिल हो। बाइट्स में बफ़र का आकार, माइनस ऑफ़सेट , प्रारूप द्वारा आवश्यक कम से कम आकार होना चाहिए, जैसा कि calcsize() द्वारा परिलक्षित होता है।

struct.iter_unpack(format, buffer)

प्रारूप स्ट्रिंग प्रारूप के अनुसार बफर बफर से Iteratively अनपैक करें। यह फ़ंक्शन एक पुनरावृत्ति देता है जो बफ़र से समान रूप से आकार के विखंडू को पढ़ेगा जब तक कि इसकी सभी सामग्री का उपभोग नहीं किया जाता है। बाइट्स में बफ़र का आकार, स्वरूप द्वारा आवश्यक आकार का एक बहु होना चाहिए, जैसा कि calcsize() द्वारा परिलक्षित होता है।

प्रत्येक पुनरावृत्ति प्रारूप स्ट्रिंग द्वारा निर्दिष्ट के रूप में एक tuple पैदावार।

संस्करण 3.4 में नया।

struct.calcsize(format)

संरचना का आकार लौटाएँ (और इसलिए pack(format, ...) स्ट्रिंग pack(format, ...) द्वारा उत्पादित बाइट्स ऑब्जेक्ट के लिए प्रारूप स्ट्रिंग प्रारूप के अनुरूप है।

प्रारूप स्ट्रिंग्स

प्रारूप स्ट्रिंग वे तंत्र हैं जिनका उपयोग डेटा को पैकिंग और अनपैक करते समय अपेक्षित लेआउट को निर्दिष्ट करने के लिए किया जाता है। वे प्रारूप वर्णों से निर्मित होते हैं, जो निर्दिष्ट प्रकार के डेटा को पैक / अनपैक्ड करते हैं। इसके अलावा, बाइट ऑर्डर, आकार और संरेखण को नियंत्रित करने के लिए विशेष वर्ण हैं।

बाइट ऑर्डर, आकार और संरेखण

डिफ़ॉल्ट रूप से, सी प्रकार को मशीन के मूल प्रारूप और बाइट क्रम में दर्शाया जाता है, और यदि आवश्यक हो तो (सी कंपाइलर द्वारा उपयोग किए गए नियमों के अनुसार) पैड बाइट्स को छोड़ कर ठीक से गठबंधन किया जाता है।

वैकल्पिक रूप से, प्रारूप स्ट्रिंग के पहले वर्ण को बाइट ऑर्डर, पैक्ड डेटा के आकार और संरेखण को इंगित करने के लिए इस्तेमाल किया जा सकता है, निम्न तालिका के अनुसार:

चरित्र बाइट क्रम आकार संरेखण
@ देशी देशी देशी
= देशी मानक कोई नहीं
< छोटा एंडियन मानक कोई नहीं
> बड़े एंडियन मानक कोई नहीं
! नेटवर्क (= बड़ा-एंडियन) मानक कोई नहीं

यदि पहला वर्ण इनमें से नहीं है, तो '@' मान लिया जाता है।

मेजबान सिस्टम के आधार पर मूल बाइट ऑर्डर बड़े-एंडियन या छोटे-एंडियन हैं। उदाहरण के लिए, इंटेल x86 और AMD64 (x86-64) छोटे-एंडियन हैं; मोटोरोला 68000 और पावरपीसी जी 5 बड़े-एंडियन हैं; एआरएम और इंटेल इटेनियम में स्विचेबल एंडियननेस (द्वि-एंडियन) की सुविधा है। अपने सिस्टम की sys.byteorder की जांच करने के लिए sys.byteorder का उपयोग करें।

मूल आकार और संरेखण C संकलक के sizeof अभिव्यक्ति का उपयोग करके निर्धारित किया जाता है। इसे हमेशा देशी बाइट क्रम के साथ जोड़ा जाता है।

मानक आकार केवल प्रारूप चरित्र पर निर्भर करता है; तालिका को स्वरूप वर्ण अनुभाग में देखें।

'@' और '=' बीच अंतर पर ध्यान दें: दोनों देशी बाइट क्रम का उपयोग करते हैं, लेकिन बाद के आकार और संरेखण को मानकीकृत किया जाता है।

रूप '!' उन गरीब आत्माओं के लिए उपलब्ध है जो दावा करते हैं कि वे याद नहीं कर सकते हैं कि नेटवर्क बाइट ऑर्डर बड़े-एंडियन या छोटे-एंडियन हैं।

गैर-देशी बाइट ऑर्डर (बल बाइट-स्वैपिंग) को इंगित करने का कोई तरीका नहीं है; '<' या '>' के उपयुक्त विकल्प का उपयोग करें।

टिप्पणियाँ:

  1. पेडिंग केवल क्रमिक संरचना सदस्यों के बीच स्वचालित रूप से जोड़ा जाता है। एन्कोडेड संरचना की शुरुआत या अंत में कोई भी पैडिंग नहीं जोड़ी गई है।
  2. गैर-देशी आकार और संरेखण का उपयोग करते समय कोई पैडिंग नहीं जोड़ा जाता है, जैसे '<', '>', '=' और '!' के साथ।
  3. किसी विशेष प्रकार के संरेखण की आवश्यकता के लिए एक संरचना के अंत को संरेखित करने के लिए, उस प्रकार के लिए कोड के साथ प्रारूप को शून्य की गिनती के साथ समाप्त करें। Examples देखें।

वर्ण स्वरूप

प्रारूप वर्णों के निम्नलिखित अर्थ हैं; सी और पायथन मूल्यों के बीच रूपांतरण स्पष्ट रूप से उनके प्रकारों को दिया जाना चाहिए। 'मानक आकार' कॉलम मानक आकार का उपयोग करते समय बाइट्स में पैक मूल्य के आकार को संदर्भित करता है; वह है, जब प्रारूप स्ट्रिंग '<' , '>' , '!' '>' एक से शुरू होता है '!' या '=' । देशी आकार का उपयोग करते समय, पैक किए गए मूल्य का आकार प्लेटफ़ॉर्म-निर्भर है।

स्वरूप C प्रकार अजगर का प्रकार मानक आकर टिप्पणियाँ
x पैड बाइट कोई मूल्य नहीं
c char लंबाई के बाइट्स 1 1
b signed char पूर्णांक 1 (1), (3)
B unsigned char पूर्णांक 1 (3)
? _Bool bool 1 (1)
h short पूर्णांक 2 (3)
H unsigned short पूर्णांक 2 (3)
i int पूर्णांक 4 (3)
I unsigned int पूर्णांक 4 (3)
l long पूर्णांक 4 (3)
L unsigned long पूर्णांक 4 (3)
q long long पूर्णांक 8 (2), (3)
Q unsigned long long पूर्णांक 8 (2), (3)
n ssize_t पूर्णांक (4)
N size_t पूर्णांक (4)
e (7) नाव 2 (5)
f float नाव 4 (5)
d double नाव 8 (5)
s char[] बाइट्स
p char[] बाइट्स
P void * पूर्णांक (6)

संस्करण 3.3 में बदला गया : 'n' और 'N' प्रारूपों के लिए जोड़ा गया समर्थन।

संस्करण 3.6 में बदला गया : 'e' प्रारूप के लिए जोड़ा गया समर्थन।

टिप्पणियाँ:

  1. '?' रूपांतरण कोड C99 द्वारा परिभाषित _Bool प्रकार से मेल खाता है। यदि यह प्रकार उपलब्ध नहीं है, तो यह एक char का उपयोग करके सिम्युलेटेड है। मानक मोड में, इसे हमेशा एक बाइट द्वारा दर्शाया जाता है।
  2. 'q' और 'Q' रूपांतरण कोड केवल देशी मोड में उपलब्ध हैं यदि प्लेटफ़ॉर्म सी कंपाइलर सी long long या, विंडोज पर, __int64 समर्थन करता है। वे हमेशा मानक मोड में उपलब्ध हैं।
  3. किसी पूर्णांक रूपांतरण कोड का उपयोग करके एक गैर-पूर्णांक को पैक करने का प्रयास करते समय, यदि गैर-पूर्णांक में __index__() विधि होती है, तो उस विधि को तर्क को पूर्णांक में बदलने से पहले कहा जाता है।

    संस्करण 3.2 में परिवर्तित: गैर-पूर्णांक के लिए __index__() पद्धति का उपयोग 3.2 में नया है।

  4. 'n' और 'N' रूपांतरण कोड केवल देशी आकार के लिए उपलब्ध हैं (डिफ़ॉल्ट रूप में या '@' बाइट कैरेक्टर के साथ चयनित)। मानक आकार के लिए, आप अन्य पूर्णांक स्वरूपों में से जो भी आपके एप्लिकेशन को फिट करता है का उपयोग कर सकते हैं।
  5. 'f' , 'd' और 'e' रूपांतरण कोड के लिए, पैक किए गए प्रतिनिधित्व IEEE 754 बाइनरी 32, बाइनरी 64 या बाइनरी 16 फॉर्मेट (क्रमशः 'f' , 'd' या 'e' ) का उपयोग करता है, फ़्लोटिंग की परवाह किए बिना- मंच द्वारा उपयोग किया जाने वाला बिंदु प्रारूप।
  6. 'P' प्रारूप चरित्र केवल मूल बाइट ऑर्डर के लिए उपलब्ध है (डिफ़ॉल्ट रूप में या '@' बाइट ऑर्डर वर्ण के साथ चयनित)। बाइट ऑर्डर कैरेक्टर '=' होस्ट सिस्टम के आधार पर छोटे या बड़े-एंडियन ऑर्डर का उपयोग करने का विकल्प चुनता है। संरचनात्मक मॉड्यूल इसे मूल आदेश के रूप में व्याख्या नहीं करता है, इसलिए 'P' प्रारूप उपलब्ध नहीं है।
  7. IEEE 754 मानक के 2008 संशोधन में IEEE 754 बाइनरी 16 "आधा परिशुद्धता" प्रकार पेश किया गया था। इसमें एक संकेत बिट, एक 5-बिट एक्सपोर्टर और 11-बिट सटीक (10 बिट के साथ स्पष्ट रूप से संग्रहीत) है, और पूर्ण सटीकता पर लगभग 6.1e-05 और 6.5e+04 बीच संख्याओं का प्रतिनिधित्व कर सकता है। यह प्रकार सी कंपाइलरों द्वारा व्यापक रूप से समर्थित नहीं है: एक विशिष्ट मशीन पर, एक अहस्ताक्षरित शॉर्ट स्टोरेज के लिए इस्तेमाल किया जा सकता है, लेकिन गणित कार्यों के लिए नहीं। अधिक जानकारी के लिए आधा-सटीक फ़्लोटिंग-पॉइंट प्रारूप पर विकिपीडिया पृष्ठ देखें।

एक प्रारूप चरित्र एक अभिन्न दोहराने गिनती से पहले हो सकता है। उदाहरण के लिए, प्रारूप स्ट्रिंग '4h' अर्थ 'hhhh' के समान है।

प्रारूपों के बीच व्हाट्सएप के पात्रों की अनदेखी की जाती है; एक गिनती और इसके प्रारूप में हालांकि व्हॉट्सएप नहीं होना चाहिए।

's' प्रारूप चरित्र के लिए, गिनती को बाइट्स की लंबाई के रूप में व्याख्या की जाती है, अन्य प्रारूप वर्णों की तरह दोहराई जाने वाली गिनती नहीं; उदाहरण के लिए, '10s' अर्थ है एकल 10-बाइट स्ट्रिंग, जबकि '10c' अर्थ है 10 वर्ण। यदि कोई गिनती नहीं दी जाती है, तो यह 1 को डिफॉल्ट करता है। पैकिंग के लिए, स्ट्रिंग को जाली के रूप में छोटा किया जाता है या इसे उपयुक्त बनाने के लिए नल बाइट्स के साथ गद्देदार किया जाता है। अनपैकिंग के लिए, परिणामस्वरूप बाइट्स ऑब्जेक्ट में हमेशा बाइट्स की निर्दिष्ट संख्या होती है। एक विशेष मामले के रूप में, '0s' अर्थ है एक एकल, खाली स्ट्रिंग (जबकि '0c' अर्थ है 0 वर्ण)।

जब पूर्णांक प्रारूपों ( 'b' , 'B' , 'h' , 'H' , 'i' , 'I' , 'l' , 'L' , 'q' , 'Q' 'q' , 'Q' 'q' 'L' 'l' 'I' 'i' 'H' का उपयोग करते हुए वैल्यू x पैकिंग करते हैं। 'Q' ), यदि x उस प्रारूप के लिए मान्य सीमा से बाहर है, तो struct.error उठाया जाता है।

संस्करण 3.1 में परिवर्तित: 3.0 में, पूर्णांक के कुछ स्वरूपों ने श्रेणी-मानों को लपेट दिया और struct.error जगह पर DeprecationWarning उठाया।

'p' प्रारूप का चरित्र एक "पास्कल स्ट्रिंग" को एन्कोड करता है, जिसका अर्थ है कि गिनती द्वारा दिए गए बाइट्स की एक निश्चित संख्या में संग्रहीत एक छोटी चर-लंबाई स्ट्रिंग। संग्रहीत पहली बाइट स्ट्रिंग की लंबाई है, या 255, जो भी छोटा है। स्ट्रिंग के बाइट्स का पालन करें। यदि स्ट्रिंग को pack() करने के लिए पास किया गया है pack() बहुत लंबा है (गणना माइनस 1 से अधिक), तो केवल स्ट्रिंग के अग्रणी count-1 बाइट्स को संग्रहीत किया जाता है। यदि स्ट्रिंग count-1 से छोटी है, तो इसे नल बाइट्स के साथ गद्देदार किया जाता है, ताकि सभी में बाइट्स का सही उपयोग हो सके। ध्यान दें कि unpack() , 'p' फॉर्मेट कैरेक्टर count बाइट्स का उपभोग करता count , लेकिन जो स्ट्रिंग लौटी है, उसमें 255 से अधिक बाइट्स कभी नहीं हो सकते।

'?' स्वरूप वर्ण, वापसी मान या तो True या False । पैकिंग करते समय, तर्क वस्तु के सत्य मूल्य का उपयोग किया जाता है। देशी या मानक बूल प्रतिनिधित्व में या तो 0 या 1 पैक किया जाएगा, और किसी भी गैर-शून्य मान को अनपैक करते समय True होगा।

उदाहरण

ध्यान दें

सभी उदाहरण एक मूल बाइट क्रम, आकार, और एक बड़े-एंडियन मशीन के साथ संरेखित करते हैं।

तीन पूर्णांक पैकिंग / अनपैकिंग का एक मूल उदाहरण:

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

अनपैक्ड फ़ील्ड्स का नाम उन्हें वेरिएबल्स में निर्दिष्ट करके या नामांकित टुपल में लपेटकर दिया जा सकता है:

>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

संरेखण आवश्यकताओं को अलग करने के लिए आवश्यक पैडिंग के बाद से प्रारूप वर्णों के क्रम पर प्रभाव पड़ सकता है:

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

निम्नलिखित प्रारूप 'llh0l' दो पैड बाइट्स को अंत में निर्दिष्ट करता है, यह मानते हुए कि 'llh0l' को 4- 'llh0l' पर संरेखित किया गया है:

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

यह तभी काम करता है जब मूल आकार और संरेखण प्रभाव में होते हैं; मानक आकार और संरेखण किसी संरेखण को लागू नहीं करता है।

यह भी देखें

Module array
सजातीय डेटा का बाइनरी स्टोरेज।
Module xdrlib
XDR डेटा की पैकिंग और अनपैकिंग।

कक्षाएं

struct मॉड्यूल निम्नलिखित प्रकार को भी परिभाषित करता है:

class struct.Struct(format)

एक नया स्ट्रक्चर ऑब्जेक्ट लौटाएं जो प्रारूप स्ट्रिंग प्रारूप के अनुसार बाइनरी डेटा लिखता है और पढ़ता है। एक बार एक स्ट्रक्चर ऑब्जेक्ट बनाना और उसके तरीकों को कॉल करना एक ही प्रारूप के साथ struct फ़ंक्शन को कॉल करने की तुलना में अधिक कुशल है क्योंकि प्रारूप स्ट्रिंग को केवल एक बार संकलित करने की आवश्यकता है।

ध्यान दें

सबसे हाल ही में प्रारूप स्ट्रिंग्स के संकलित संस्करणों को Struct और मॉड्यूल-स्तर के कार्यों के लिए पारित किया गया है, इसलिए केवल कुछ प्रारूप स्ट्रिंग का उपयोग करने वाले कार्यक्रमों को एकल Struct उदाहरण के पुन: उपयोग के बारे में चिंता करने की आवश्यकता नहीं है।

संकलित संरचना वस्तुएँ निम्नलिखित विधियों और विशेषताओं का समर्थन करती हैं:

pack(v1, v2, ...)

संकलित प्रारूप का उपयोग करके pack() फ़ंक्शन की पहचान। ( len(result) बराबर size होगा।)

pack_into(buffer, offset, v1, v2, ...)

संकलित प्रारूप का उपयोग करके pack_into() फ़ंक्शन के लिए समान है।

unpack(buffer)

संकलित प्रारूप का उपयोग करते हुए unpack() फ़ंक्शन के लिए पहचान। बाइट्स में बफ़र का आकार समान size होना चाहिए।

unpack_from(buffer, offset=0)

संकलित प्रारूप का उपयोग करते हुए unpack_from() फ़ंक्शन के लिए समान है। बाइट्स में बफ़र का आकार, माइनस ऑफ़सेट , कम से कम size होना चाहिए।

iter_unpack(buffer)

संकलित प्रारूप का उपयोग करके iter_unpack() फ़ंक्शन के लिए समान है। बाइट्स में बफ़र का आकार कई size का होना चाहिए।

संस्करण 3.4 में नया।

format

इस स्ट्रक्च ऑब्जेक्ट को बनाने के लिए फॉर्मेट स्ट्रिंग का उपयोग किया जाता है।

संस्करण 3.7 में परिवर्तित: प्रारूप स्ट्रिंग प्रकार bytes बजाय अब स्ट्रिंग है।

size

format अनुरूप संरचना (और इसलिए pack() विधि द्वारा उत्पादित बाइट्स ऑब्जेक्ट की गणना आकार।