दस्तावेज़ प्रबंधन

दस्तावेज़ प्रबंधन

Document क्लास लगभग हर ऑपरेशन के लिए Aspose.PDF FOSS for Python में प्रवेश बिंदु है: नया PDF बनाना, मौजूदा को लोड करना, उसके पृष्ठों को संपादित करना, और परिणाम को वापस लिखना। यह गाइड दस्तावेज़ जीवनचक्र, पृष्ठ-संग्रह ऑपरेशन्स, अनुकूलन, मल्टी-फ़ाइल वर्कफ़्लो, एन्क्रिप्शन, और उन अपवादों को जो आप संभालने की उम्मीद कर सकते हैं, के माध्यम से चलता है।

दस्तावेज़ जीवनचक्र: बनाना, खोलना, और सहेजना

Document() बिना किसी तर्क के एक खाली, इन-मेमारी दस्तावेज़ बनाता है। एक फ़ाइल पाथ, कच्चा bytes, या कोई भी पढ़ने योग्य बाइनरी स्ट्रीम को पहले तर्क के रूप में पास करें (या स्पष्ट रूप से load_from() को कॉल करें) ताकि मौजूदा PDF लोड हो सके। save() एक पाथ या लिखने योग्य बाइनरी स्ट्रीम जैसे io.BytesIO को स्वीकार करता है।

from aspose_pdf import Document

# Create a new, empty document and add a blank page
doc = Document()
doc.pages.add()
doc.save("hello.pdf")

# Re-open it — a path, bytes, or a binary stream all work
reopened = Document("hello.pdf")
print(reopened.page_count)   # 1

# ...or load explicitly onto an existing instance
another = Document()
another.load_from("hello.pdf")

reopened.close()
another.dispose()
doc.dispose()

save() FileExistsError उठाता है यदि लक्षित पाथ पहले से मौजूद है, जब तक आप overwrite=True न पास करें। close() dispose() का उपनाम है; दोनों आइडेम्पोटेंट हैं, इसलिए उन्हें एक से अधिक बार कॉल करना सुरक्षित है।

केवल PDF को सहेजने के लक्ष्य के रूप में लागू किया गया है — यह लाइब्रेरी का कोर, पूरी तरह कार्यात्मक फ़ंक्शन है। SaveFormat.PPTX या DocFormat.HTML जैसे निर्यात मान को save() में पास करने पर UnsupportedFeatureException उठता है, बजाय गलत लेबल वाली फ़ाइल लिखने के, इसलिए विफल निर्यात हमेशा स्पष्ट रूप से त्रुटि देता है, चुप नहीं रहता।

पृष्ठ संग्रह का प्रबंधन

doc.pages एक PageCollection है। यह len(), पुनरावृत्ति, और 0-आधारित अनुक्रमण (doc.pages[0]) का समर्थन करता है, साथ ही संरचनात्मक संपादन के लिए add(), insert(index, page), और delete(index) प्रदान करता है। प्रत्येक Page index, rect (जो MediaBox है), और rotation को उजागर करता है।

from aspose_pdf import Document

doc = Document()
doc.pages.add()            # page 0
doc.pages.add()            # page 1
doc.pages.insert(1, None)  # insert a blank page at index 1

print(doc.page_count)      # 3

first_page = doc.pages[0]
print(first_page.rect)     # (0, 0, 612, 792)

for page in doc.pages:
    print(page.index, page.rotation)

doc.pages.delete(1)        # remove the page we inserted
doc.save("pages_demo.pdf", overwrite=True)

pages.add(page=None) बिना किसी तर्क के बुलाए जाने पर एक खाली पृष्ठ जोड़ता है। pages.insert() बाहर की सीमा वाले सूचकांक को निकटतम वैध स्थिति पर सीमित करता है, बजाय त्रुटि उत्पन्न करने के।

दस्तावेज़ों का अनुकूलन और संपीड़न

Document.optimize एक ही कॉल में छवि/स्ट्रीम डिडुप्लीकेशन, अप्रयुक्त-ऑब्जेक्ट गैरेज कलेक्शन, और स्ट्रीम संपीड़न चलाता है। कौन सी तकनीकें चलेंगी इसे नियंत्रित करने के लिए एक OptimizationOptions इंस्टेंस पास करें; मानक सफ़ाई प्रोफ़ाइल उपयोग करने के लिए इसे छोड़ दें।

from aspose_pdf import Document, OptimizationOptions

doc = Document("large_report.pdf")

options = OptimizationOptions()
options.remove_unused_objects = True
options.link_duplicate_streams = True
options.image_compression_quality = 60
options.subset_fonts = True

doc.optimize(options)
doc.save("large_report_optimized.pdf", overwrite=True)

optimize_resources() optimize() का उपनाम है। यदि आप केवल संरचनात्मक सफ़ाई पास के बिना स्ट्रीम संपीड़न चाहते हैं, तो सीधे doc.compress_streams() को कॉल करें।

फ़ाइलों का मिलाना, विभाजन, और संपादन

उन दस्तावेज़ों के लिए जो आपने पहले ही खोल रखे हैं, Document.merge() अन्य Document इंस्टेंस को वर्तमान पर जोड़ता है:

from aspose_pdf import Document

base = Document("part1.pdf")
extra = Document("part2.pdf")

base.merge(extra)
base.save("combined.pdf", overwrite=True)

फ़ाइल-से-फ़ाइल वर्कफ़्लो के लिए, बिना स्वयं Document खोले, लो-कोड Merger और Splitter प्लगइन्स FileDataSource इनपुट और आउटपुट से निर्मित MergeOptions/SplitOptions ऑब्जेक्ट लेती हैं:

from aspose_pdf import Merger, MergeOptions, Splitter, SplitOptions, FileDataSource

# Merge two files into one
merge_options = MergeOptions()
merge_options.add_input(FileDataSource("part1.pdf"))
merge_options.add_input(FileDataSource("part2.pdf"))
merge_options.add_output(FileDataSource("combined.pdf"))
Merger().process(merge_options)

# Split the result into one file per page
split_options = SplitOptions()
split_options.add_input(FileDataSource("combined.pdf"))
split_options.add_output(FileDataSource("combined_page1.pdf"))
split_options.add_output(FileDataSource("combined_page2.pdf"))
Splitter().process(split_options)

PdfFileEditor वही ऑपरेशन्स का समूह एक फ़ेसाड के रूप में प्रदान करता है जो True/False लौटाता है न कि एक्सेप्शन उछालता है, जो बैच स्क्रिप्ट्स के लिए सुविधाजनक है:

from aspose_pdf import PdfFileEditor

with PdfFileEditor() as editor:
    ok = editor.concatenate(["part1.pdf", "part2.pdf"], "combined.pdf")
    if not ok:
        print("concatenate failed:", editor.last_exception)

    editor.extract("combined.pdf", "first_page_only.pdf", page_from=1, page_to=1)

PdfFileEditor.extract() and .insert() take 1-आधारित पृष्ठ संख्याएँ, अलग PageCollectionका 0-आधारित अनुक्रमण — देखें सामान्य समस्याएँ नीचे।

एन्क्रिप्शन और दस्तावेज़ सुरक्षा

Document.encrypt(user_password, owner_password=None, permissions=-4) मेमोरी में मौजूद दस्तावेज़ को एन्क्रिप्ट करता है; decrypt(password) और change_passwords(old, new_user, new_owner=None) पासवर्ड को उलटते या घुमाते हैं। is_encrypted और permissions वर्तमान स्थिति की रिपोर्ट करते हैं।

from aspose_pdf import Document
from aspose_pdf.exceptions import PdfSecurityException

doc = Document()
doc.pages.add()
doc.encrypt("user-pass", "owner-pass", permissions=-4)
doc.save("secured.pdf", overwrite=True)

try:
    Document("secured.pdf", password="wrong-pass")
except PdfSecurityException as exc:
    print("could not open:", exc)

reopened = Document("secured.pdf", password="user-pass")
print(reopened.is_encrypted)   # True
reopened.decrypt("user-pass")
reopened.save("unsecured.pdf", overwrite=True)

बिना पासवर्ड या गलत पासवर्ड के एन्क्रिप्टेड दस्तावेज़ को खोलने पर PdfSecurityException उछाला जाता है — इस क्लास को (aspose_pdf.exceptions से) पकड़ें, न कि यह मान लें कि लोड हमेशा सफल होगा।

मेटाडेटा, वैलिडेशन, और एक्सेप्शन हैंडलिंग

दस्तावेज़ मेटाडेटा doc.info पर रहता है (एक साधारण dict[str, str]), और doc.version / doc.id PDF हेडर संस्करण और ट्रेलर फ़ाइल-आईडेंटिफ़ायर उजागर करते हैं। validate() (जिसे check() कहा जाता है) संरचनात्मक अखंडता की रिपोर्ट करता है; repair() सामान्य समस्याओं जैसे कि गायब पेज सूची या सीमा से बाहर MediaBox को ठीक करने का प्रयास करता है।

from aspose_pdf import Document, PdfLoadLimits
from aspose_pdf.exceptions import AsposePdfException, PdfIOException

doc = Document()
doc.pages.add()
doc.info["Title"] = "Quarterly Report"
doc.info["Author"] = "Reporting Bot"
doc.save("report.pdf", overwrite=True)

# Load untrusted input under an explicit resource-limit policy
safe_limits = PdfLoadLimits(max_input_bytes=50 * 1024 * 1024, max_pages=1000)

try:
    untrusted = Document("incoming.pdf", limits=safe_limits)
    if not untrusted.validate():
        untrusted.repair()
except (AsposePdfException, PdfIOException) as exc:
    print("failed to process incoming.pdf:", exc)

PdfLoadLimits अविश्वसनीय फाइलों के लिए मेमोरी और ऑब्जेक्ट काउंट को सीमित करता है; जब आप स्रोत पर पूरी तरह भरोसा करते हैं तो सभी सीमाओं को निष्क्रिय करने के लिए PdfLoadLimits.unlimited() को कॉल करें। AsposePdfException पूरी एक्सेप्शन पदानुक्रम का बेस क्लास है (जिसमें PdfIOException और PdfSecurityException शामिल हैं), इसलिए एक ही except AsposePdfException किसी भी लाइब्रेरी-उठाए गए त्रुटि को पकड़ लेता है।

सलाह और सर्वोत्तम प्रथाएँ

• जब आप इसे समाप्त कर लें, तो हमेशा dispose() (या close()) को Document पर कॉल करें, या इसे एक अल्पकालिक स्थानीय चर के रूप में उपयोग करें — इंजन डिस्पोज़ल तक डिकोडेड पेज कंटेंट और इमेजेज को मेमोरी में रखता है।
• जब आप उसी रन में पहले बनाया हुआ पाथ पुनः लिख रहे हों, तो overwrite=True को save() में पास करें; डिफ़ॉल्ट False है और यह FileExistsError उठाता है।
• जेनरेटेड PDF को शिप करने से पहले doc.optimize() को प्राथमिकता दें — यह एकसिंगल कॉल है जो अनउपयोगी ऑब्जेक्ट्स को हटाता है और स्ट्रीम्स को कॉम्प्रेस करता है, और आमतौर पर आउटपुट साइज को उल्लेखनीय रूप से घटाता है।
• जब भी आप अनविश्वसनीय स्रोत (अपलोड्स, ईमेल अटैचमेंट्स, वेब स्क्रैप्स) से PDFs लोड करें, तब एक PdfLoadLimits नीति स्पष्ट रूप से सेट करें; डिफ़ॉल्ट्स उदार लेकिन सीमित होते हैं, यह कोई सुरक्षा सीमा नहीं है जिस पर आप अंधाधुंध भरोसा कर सकें।
• लोड/सेव कॉल्स के आसपास AsposePdfException (या PdfSecurityException जैसी विशिष्ट सबक्लास) को कैच करें, न कि सीधे Exception — यह लाइब्रेरी द्वारा उठाए जाने वाले प्रत्येक त्रुटि का सामान्य बेस है।

सामान्य समस्याएँ

FAQ

क्या मुझे Aspose.PDF FOSS को Python के लिए उपयोग करने के लिए लाइसेंस की आवश्यकता है?

नहीं। यह ओपन-सोर्स (MIT-लाइसेंस वाला) संस्करण है; कॉन्फ़िगर करने के लिए कोई लाइसेंस फ़ाइल या सक्रियण चरण नहीं है।

क्या मैं Document को PDF के अलावा अन्य फ़ॉर्मैट में निर्यात कर सकता हूँ?

इस रिलीज़ में नहीं। save() केवल PDF आउटपुट को लागू करता है — कोई अन्य SaveFormat/DocFormat मान पास करने पर UnsupportedFeatureException उठाया जाता है, न कि गलत लेबल वाली फ़ाइल बनती है।

Document.merge() और Merger प्लगइन के बीच क्या अंतर है?

Document.merge() उन Document इंस्टेंस को मिलाता है जो आप पहले से मेमोरी में खुले हुए हैं। Merger (MergeOptions और FileDataSource के साथ) एक फ़ाइल-से-फ़ाइल सुविधा रैपर है जो एक कॉल में आपके लिए खोलता, मिलाता और सहेजता है — सरल बैच स्क्रिप्ट्स के लिए उपयोगी जो कभी भी मध्यवर्ती Document ऑब्जेक्ट की आवश्यकता नहीं रखते।

क्यों pages.insert() कभी भी out-of-range इंडेक्स के लिए त्रुटि नहीं उठाता?

PageCollection.insert() इंडेक्स को वैध रेंज में क्लैंप करता है (नकारात्मक मान 0 बन जाते हैं, अंत से आगे के मान len(doc.pages) बन जाते हैं) त्रुटि उठाने के बजाय, इसलिए एक insert केवल इंडेक्स मान के कारण कभी विफल नहीं होता।

मैं अविश्वसनीय स्रोत से PDF को सुरक्षित रूप से कैसे लोड करूँ?

एक PdfLoadLimits बनाएँ जिसमें स्पष्ट सीमाएँ हों (max_input_bytes, max_pages, max_objects, आदि) और इसे limits= आर्गुमेंट के रूप में Document(...) या load_from() को पास करें। प्रत्येक फ़ील्ड पहले से ही एक सीमित मान पर डिफ़ॉल्ट होता है, लेकिन उन्हें आपके अपेक्षित इनपुट आकार के अनुसार कड़ा करने से एक विकृत फ़ाइल द्वारा उपयोग किए जा सकने वाले संसाधनों को कम किया जा सकता है।

API Reference सारांश

यह भी देखें

• API Reference: पूर्ण वर्ग और विधि दस्तावेज़ीकरण के लिए aspose_pdf
• ज्ञान आधार: कार्य-उन्मुख कैसे-करें गाइड
• उत्पाद अवलोकन: सुविधाओं और क्षमताओं का सारांश
• शुरूआत / स्थापना: इंस्टॉल और सेटअप
• Aspose.PDF for Python — Enterprise Documentation