winreg --- دسترسی به رجیستری ویندوز¶
این توابع API رجیستری ویندوز را در اختیار پایتون قرار میدهند. بهجای استفاده از یک عدد صحیح بهعنوان دستهی رجیستری، از یک شیء دسته استفاده میشود تا اطمینان حاصل شود که دستهها بهدرستی بسته شوند، حتی اگر برنامهنویس از بستن آنها بهصورت صریح غفلت کند.
دسترسپذیری: Windows.
تغییر یافته در نسخهی 3.3: چند تابع در این ماژول پیشتر WindowsError را پرتاب میکردند، که اکنون نام مستعاری از OSError است.
توابع¶
این ماژول توابع زیر را ارائه میدهد:
- winreg.CloseKey(hkey)¶
یک کلید رجیستری را که پیشتر بازشده است میبندد. آرگومان hkey یک کلید را که پیشتر بازشده است مشخص میکند.
توجه
اگر hkey با استفاده از این متد (یا از طریق
hkey.Close()) بسته نشود، هنگامی که شیء hkey توسط پایتون تخریب شود، بسته میشود.
- winreg.ConnectRegistry(computer_name, key)¶
اتصالی به یک دستهی رجیستری از پیش تعریفشده در رایانهای دیگر برقرار میکند و یک شیء دسته برمیگرداند.
computer_name نام رایانه راه دور است، به شکل
r"\\computername". اگرNoneباشد، از رایانه محلی استفاده میشود.key دستهی از پیش تعریفشده برای اتصال است.
مقدار بازگشتی، دستهی کلید بازشده است. اگر تابع با شکست مواجه شود، یک استثنای
OSErrorپرتاب میشود.یک رویداد حسابرسی
winreg.ConnectRegistryرا با آرگومانهایcomputer_nameوkeyپرتاب میکند.تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.CreateKey(key, sub_key)¶
کلید مشخصشده را ایجاد یا باز میکند و یک شیء دسته برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key یک رشته است که نام کلیدی را که این متد آن را باز یا ایجاد میکند، مشخص میکند.
اگر key یکی از کلیدهای از پیش تعریفشده باشد، sub_key میتواند
Noneباشد. در آن حالت، دسته برگرداندهشده همان دستهی کلید (key handle) است که به تابع دادهشده است.اگر کلید از قبل وجود داشته باشد، این تابع کلید موجود را باز میکند.
مقدار بازگشتی، دستهی کلید بازشده است. اگر تابع با شکست مواجه شود، یک استثنای
OSErrorپرتاب میشود.یک رویداد حسابرسی
winreg.CreateKeyرا با آرگومانهایkey،sub_keyوaccessپرتاب میکند.یک رویداد حسابرسی
winreg.OpenKey/resultرا با آرگومانkeyپرتاب میکند.تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)¶
کلید مشخصشده را ایجاد یا باز میکند و یک شیء دسته برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key یک رشته است که نام کلیدی را که این متد آن را باز یا ایجاد میکند، مشخص میکند.
reserved یک عدد صحیح رزروشده است و باید صفر باشد. مقدار پیشفرض صفر است.
access یک عدد صحیح است که یک نقاب دسترسی (access mask) را مشخص میکند؛ این نقاب، دسترسی امنیتی موردنظر برای کلید را توصیف میکند. پیشفرض
KEY_WRITEاست. برای سایر مقادیر مجاز، Access Rights را ببینید.اگر key یکی از کلیدهای از پیش تعریفشده باشد، sub_key میتواند
Noneباشد. در آن حالت، دسته برگرداندهشده همان دستهی کلید (key handle) است که به تابع دادهشده است.اگر کلید از قبل وجود داشته باشد، این تابع کلید موجود را باز میکند.
مقدار بازگشتی، دستهی کلید بازشده است. اگر تابع با شکست مواجه شود، یک استثنای
OSErrorپرتاب میشود.یک رویداد حسابرسی
winreg.CreateKeyرا با آرگومانهایkey،sub_keyوaccessپرتاب میکند.یک رویداد حسابرسی
winreg.OpenKey/resultرا با آرگومانkeyپرتاب میکند.اضافه شده در نسخهی 3.2.
تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.DeleteKey(key, sub_key)¶
کلید مشخصشده را حذف میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key یک رشته است که باید یک زیرکلید از کلید شناساییشده با پارامتر key باشد. این مقدار نباید
Noneباشد، و کلید نمیتواند زیرکلید داشته باشد.این متد نمیتواند کلیدهای دارای زیرکلید را حذف کند.
اگر متد موفق شود، کلید بهطور کامل، شامل تمام مقدارهای آن، حذف میشود. اگر متد ناموفق باشد، استثنای
OSErrorپرتاب میشود.یک رویداد حسابرسی
winreg.DeleteKeyرا با آرگومانهایkey،sub_keyوaccessپرتاب میکند.تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶
کلید مشخصشده را حذف میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key رشتهای است که باید زیرکلیدی از کلید مشخصشده با پارامتر key باشد. این مقدار نباید
Noneباشد، و کلید نباید زیرکلید داشته باشد.reserved یک عدد صحیح رزروشده است و باید صفر باشد. مقدار پیشفرض صفر است.
access عدد صحیحی است که نقاب دسترسیای را مشخص میکند که دسترسی امنیتی موردنظر برای کلید را توصیف میکند. مقدار پیشفرض
KEY_WOW64_64KEYاست. در ویندوز ۳۲ بیتی، ثابتهای WOW64 نادیده گرفته میشوند. برای سایر مقادیر مجاز، حقوق دسترسی را ببینید.این متد نمیتواند کلیدهای دارای زیرکلید را حذف کند.
اگر متد موفق شود، کلید بهطور کامل، شامل تمام مقدارهای آن، حذف میشود. اگر متد ناموفق باشد، استثنای
OSErrorپرتاب میشود.در نسخههای پشتیبانینشده ویندوز،
NotImplementedErrorپرتاب میشود.یک رویداد حسابرسی
winreg.DeleteKeyرا با آرگومانهایkey،sub_keyوaccessپرتاب میکند.اضافه شده در نسخهی 3.2.
تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.DeleteValue(key, value)¶
یک مقدار نامدار را از یک کلید رجیستری حذف میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
value یک رشته است که مقدار مورد نظر برای حذف را شناسایی میکند.
یک رویداد حسابرسی
winreg.DeleteValueرا با آرگومانهایkeyوvalueپرتاب میکند.
- winreg.EnumKey(key, index)¶
زیرکلیدهای یک کلید رجیستری باز را فهرست میکند و یک رشته برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
index یک عدد صحیح است که اندیس کلیدِ موردنظر برای بازیابی را مشخص میکند.
این تابع هر بار که فراخوانی میشود، نام یک زیرکلید را بازیابی میکند. این تابع معمولاً بهطور مکرر فراخوانی میشود تا زمانی که استثنای
OSErrorپرتاب شود، که نشان میدهد دیگر مقداری در دسترس نیست.یک رویداد حسابرسی
winreg.EnumKeyرا با آرگومانهایkeyوindexپرتاب میکند.تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.EnumValue(key, index)¶
مقادیر یک کلید رجیستری باز را برمیشمارد و یک تاپل برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
index یک عدد صحیح است که اندیس مقدار مورد نظر برای بازیابی را مشخص میکند.
این تابع هر بار که فراخوانی میشود، نام یک زیرکلید را بازیابی میکند. معمولاً بهطور مکرر فراخوانی میشود، تا زمانی که یک استثنای
OSErrorپرتاب شود که نشان میدهد مقادیر بیشتری وجود ندارد.نتیجه، تاپلی شامل ۳ آیتم است:
اندیس
معنی
0رشتهای که نام مقدار را شناسایی میکند
1شیءای که دادههای مقدار را نگه میدارد و نوع آن به نوع رجیستری (registry) زیربنایی وابسته است
2عدد صحیحی که نوع دادهی مقدار را مشخص میکند (جدول موجود در مستندات
SetValueEx()را ببینید)یک رویداد حسابرسی
winreg.EnumValueرا با آرگومانهایkeyوindexپرتاب میکند.تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.ExpandEnvironmentStrings(str)¶
جاینگهدارهای متغیر محیطی
%NAME%را در رشتههایی مانندREG_EXPAND_SZبسط میدهد:>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
یک رویداد حسابرسی
winreg.ExpandEnvironmentStringsرا با آرگومانstrپرتاب میکند.
- winreg.FlushKey(key)¶
تمام ویژگیهای یک کلید را در رجیستری مینویسد.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
برای تغییر یک کلید، نیازی به فراخوانی
FlushKey()نیست. تغییرات رجیستری توسط رجیستری و با استفاده از تخلیهکنندهی تنبل (lazy flusher) آن به دیسک تخلیه میشوند. تغییرات رجیستری همچنین در زمان خاموش شدن سیستم به دیسک تخلیه میشوند. برخلافCloseKey()، متدFlushKey()تنها زمانی بازمیگردد که تمام دادهها در رجیستری نوشته شده باشند. یک برنامه باید تنها در صورتیFlushKey()را فراخوانی کند که به اطمینان کامل نیاز داشته باشد که تغییرات رجیستری روی دیسک قرار دارند.توجه
اگر نمیدانید که آیا فراخوانی
FlushKey()لازم است یا خیر، احتمالاً لازم نیست.
- winreg.LoadKey(key, sub_key, file_name)¶
یک زیرکلید زیر کلید مشخصشده ایجاد میکند و اطلاعات ثبت را از یک پرونده مشخصشده در آن زیرکلید ذخیره میکند.
key یک دسته برگرداندهشده توسط
ConnectRegistry()یا یکی از ثابتهایHKEY_USERSیاHKEY_LOCAL_MACHINEاست.sub_key رشتهای است که زیرکلید مورد نظر برای بارگذاری را شناسایی میکند.
file_name نام پروندهای است که دادههای رجیستری از آن بارگذاری میشود. این پرونده باید با تابع
SaveKey()ایجاد شده باشد. در سامانه فایلبندی جدول تخصیص پرونده (FAT)، ممکن است نام پرونده پسوند نداشته باشد.اگر فرآیند فراخوانیکننده امتیاز
SE_RESTORE_PRIVILEGEرا نداشته باشد، فراخوانیLoadKey()با شکست مواجه میشود. توجه داشته باشید که امتیازها با مجوزها متفاوت هستند — برای جزئیات بیشتر، مستندات RegLoadKey را ببینید.اگر key یک دسته باشد که توسط
ConnectRegistry()برگرداندهشده است، آنگاه مسیر مشخصشده در file_name نسبت به رایانه راهدور است.یک رویداد حسابرسی
winreg.LoadKeyرا با آرگومانهایkey،sub_keyوfile_nameپرتاب میکند.
- winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)¶
- winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)¶
کلید مشخصشده را باز میکند و یک handle object برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key یک رشته است که sub_key را برای باز کردن شناسایی میکند.
reserved یک عدد صحیح رزروشده است و باید ۰ باشد. مقدار پیشفرض ۰ است.
access یک عدد صحیح است که یک نقاب دسترسی را مشخص میکند و دسترسی امنیتی موردنظر برای کلید را توصیف میکند. مقدار پیشفرض
KEY_READاست. برای سایر مقادیر مجاز، Access Rights را ببینید.نتیجه یک دسته جدید برای کلید مشخصشده است.
اگر تابع با شکست مواجه شود،
OSErrorپرتاب میشود.یک رویداد حسابرسی
winreg.OpenKeyرا با آرگومانهایkey،sub_key،accessپرتاب میکند.یک رویداد حسابرسی
winreg.OpenKey/resultرا با آرگومانkeyپرتاب میکند.تغییر یافته در نسخهی 3.2: اجازهی استفاده از آرگومانهای نامدار.
تغییر یافته در نسخهی 3.3: بالا را ببینید.
- winreg.QueryInfoKey(key)¶
اطلاعات مربوط به یک کلید را بهصورت یک تاپل برمیگرداند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
نتیجه، تاپلی شامل ۳ آیتم است:
اندیس
معنی
0عدد صحیحی که تعداد زیرکلیدهای این کلید را نشان میدهد.
1یک عدد صحیح که تعداد مقادیر این کلید را نشان میدهد.
2یک عدد صحیح که زمان آخرین تغییر کلید (در صورت در دسترس بودن) را بر حسب ۱۰۰ نانوثانیه از ۱ ژانویه ۱۶۰۱ نشان میدهد.
یک رویداد حسابرسی
winreg.QueryInfoKeyرا با آرگومانkeyپرتاب میکند.
- winreg.QueryValue(key, sub_key)¶
مقدار بینام برای یک کلید را بهصورت یک رشته بازیابی میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key یک رشته است که نام زیرکلید مرتبط با مقدار را در خود نگه میدارد. اگر این پارامتر
Noneیا خالی باشد، تابع مقدار تنظیمشده توسط متدSetValue()برای کلید مشخصشده با key را بازیابی میکند.مقادیر موجود در رجیستری دارای کامپوننتهای نام، نوع و داده هستند. این متد دادهی اولین مقدار یک کلید را که نام آن
NULLاست، بازیابی میکند. اما فراخوانی API زیربنایی نوع را برنمیگرداند، بنابراین در صورت امکان همیشه ازQueryValueEx()استفاده کنید.یک رویداد حسابرسی
winreg.QueryValueرا با آرگومانهایkey،sub_keyوvalue_nameپرتاب میکند.
- winreg.QueryValueEx(key, value_name)¶
نوع و دادهها را برای نام مقدار مشخصِ مرتبط با یک کلید رجیستری باز، بازیابی میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
value_name رشتهای است که مقدار مورد پرسوجو را نشان میدهد.
نتیجه یک تاپل با ۲ آیتم است:
اندیس
معنی
0مقدار آیتم رجیستری.
1عدد صحیحی که نوع رجیستری این مقدار را مشخص میکند (جدول موجود در مستندات
SetValueEx()را ببینید)یک رویداد حسابرسی
winreg.QueryValueرا با آرگومانهایkey،sub_keyوvalue_nameپرتاب میکند.
- winreg.SaveKey(key, file_name)¶
کلید مشخصشده و تمام زیرکلیدهای آن را در پرونده مشخصشده ذخیره میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
file_name نام پروندهای است که دادههای رجیستری در آن ذخیره میشود. این پرونده نمیتواند از قبل وجود داشته باشد. اگر این نام پرونده شامل پسوند باشد، نمیتوان از آن در سیستمهای پرونده جدول تخصیص پرونده (FAT) توسط متد
LoadKey()استفاده کرد.اگر key نمایانگر یک کلید روی یک رایانه راهدور باشد، مسیری که file_name توصیف میکند نسبت به رایانه راهدور نسبی است. فراخوانندهی این متد باید دارای امتیاز امنیتی SeBackupPrivilege باشد. توجه داشته باشید که امتیازها با مجوزها تفاوت دارند — برای جزئیات بیشتر، مستندات تعارض میان حقوق کاربر و مجوزها را ببینید.
این تابع
NULLرا برای security_attributes به API ارسال میکند.یک رویداد حسابرسی
winreg.SaveKeyرا با آرگومانهایkey،file_nameپرتاب میکند.
- winreg.SetValue(key, sub_key, type, value)¶
یک مقدار را به یک کلید مشخص مرتبط میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
sub_key رشتهای است که نام زیرکلیدی را که مقدار با آن مرتبط است، مشخص میکند.
type یک عدد صحیح است که نوع داده را مشخص میکند. در حال حاضر این باید
REG_SZباشد، به این معنا که فقط رشتهها پشتیبانی میشوند. برای پشتیبانی از انواع دیگر داده از تابعSetValueEx()استفاده کنید.value یک رشته است که مقدار جدید را مشخص میکند.
اگر کلید مشخصشده با پارامتر sub_key وجود نداشته باشد، تابع SetValue آن را ایجاد میکند.
طول مقادیر به حافظهی در دسترس محدود است. مقادیر طولانی (بیش از ۲۰۴۸ بایت) باید بهصورت پرونده ذخیره شوند و نام پروندهها در رجیستری پیکربندی ذخیره شود. این کار به عملکرد کارآمد رجیستری کمک میکند.
کلید مشخصشده با پارامتر key باید با دسترسی
KEY_SET_VALUEباز شده باشد.یک رویداد حسابرسی
winreg.SetValueرا با آرگومانهایkey،sub_key،typeوvalueپرتاب میکند.
- winreg.SetValueEx(key, value_name, reserved, type, value)¶
دادهها را در فیلد مقدار یک کلید رجیستری باز ذخیره میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
value_name رشتهای است که نام زیرکلید مرتبط با مقدار را مشخص میکند.
reserved میتواند هر مقداری باشد — همیشه صفر به API ارسال میشود.
type یک عدد صحیح است که نوع داده را مشخص میکند. برای انواع موجود، انواع مقدار را ببینید.
value یک رشته است که مقدار جدید را مشخص میکند.
این متد همچنین میتواند اطلاعات اضافی مقدار و نوع را برای کلید مشخصشده تنظیم کند. کلید شناساییشده توسط پارامتر key باید با دسترسی
KEY_SET_VALUEباز شده باشد.برای باز کردن کلید، از متدهای
CreateKey()یاOpenKey()استفاده کنید.طول مقادیر به حافظهی در دسترس محدود است. مقادیر طولانی (بیش از ۲۰۴۸ بایت) باید بهصورت پرونده ذخیره شوند و نام پروندهها در رجیستری پیکربندی ذخیره شود. این کار به عملکرد کارآمد رجیستری کمک میکند.
یک رویداد حسابرسی
winreg.SetValueرا با آرگومانهایkey،sub_key،typeوvalueپرتاب میکند.
- winreg.DisableReflectionKey(key)¶
بازتاب رجیستری (registry reflection) را برای فرآیندهای ۳۲ بیتی در حال اجرا بر روی سیستمعامل ۶۴ بیتی غیرفعال میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
معمولاً اگر روی یک سیستمعامل ۳۲ بیتی اجرا شود،
NotImplementedErrorپرتاب میشود.اگر کلید در فهرست بازتاب نباشد، تابع با موفقیت اجرا میشود، اما هیچ اثری ندارد. غیرفعالسازی بازتاب برای یک کلید، بر بازتاب هیچیک از زیرکلیدها تأثیر نمیگذارد.
یک رویداد حسابرسی
winreg.DisableReflectionKeyرا با آرگومانkeyپرتاب میکند.
- winreg.EnableReflectionKey(key)¶
بازتاب رجیستری را برای کلید غیرفعالِ مشخصشده بازیابی میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
معمولاً اگر روی یک سیستمعامل ۳۲ بیتی اجرا شود،
NotImplementedErrorپرتاب میشود.بازگرداندن بازتاب برای یک کلید، تأثیری بر بازتاب هیچیک از زیرکلیدها ندارد.
یک رویداد حسابرسی
winreg.EnableReflectionKeyرا با آرگومانkeyپرتاب میکند.
- winreg.QueryReflectionKey(key)¶
وضعیت بازتاب کلید مشخصشده را تعیین میکند.
key یک کلید از قبل باز است، یا یکی از ثابتهای HKEY_* از پیش تعریفشده است.
اگر بازتاب غیرفعال باشد،
Trueرا برمیگرداند.معمولاً اگر روی یک سیستمعامل ۳۲ بیتی اجرا شود،
NotImplementedErrorپرتاب میشود.یک رویداد حسابرسی
winreg.QueryReflectionKeyرا با آرگومانkeyپرتاب میکند.
ثابتها¶
ثابتهای زیر برای استفاده در بسیاری از توابع winreg تعریف شدهاند.
ثابتهای HKEY_*¶
- winreg.HKEY_CLASSES_ROOT¶
ورودیهای رجیستری زیرمجموعهی این کلید، انواع (یا کلاسهای) اسناد و ویژگیهای مرتبط با آن انواع را تعریف میکنند. برنامههای پوسته و COM از اطلاعات ذخیرهشده در زیر این کلید استفاده میکنند.
- winreg.HKEY_CURRENT_USER¶
ورودیهای رجیستری زیرمجموعهی این کلید، ترجیحات کاربر جاری را مشخص میکنند. این ترجیحات شامل تنظیمات متغیرهای محیطی، دادههایی دربارهی گروههای برنامه، رنگها، چاپگرها، اتصالهای شبکه و ترجیحات برنامهها میشوند.
- winreg.HKEY_LOCAL_MACHINE¶
ورودیهای رجیستری زیرمجموعهی این کلید، وضعیت فیزیکی رایانه را تعریف میکنند، از جمله دادههایی دربارهی نوع گذرگاه، حافظهی سیستم و سختافزار و نرمافزار نصبشده.
- winreg.HKEY_USERS¶
ورودیهای رجیستری زیرمجموعه این کلید، پیکربندی پیشفرض کاربر برای کاربران جدید در رایانه محلی و پیکربندی کاربر برای کاربر جاری را تعریف میکنند.
- winreg.HKEY_PERFORMANCE_DATA¶
ورودیهای رجیستری زیرمجموعهی این کلید به شما امکان میدهند به دادههای کارایی دسترسی پیدا کنید. دادهها در واقع در رجیستری ذخیره نمیشوند؛ توابع رجیستری باعث میشوند سیستم دادهها را از منبعشان جمعآوری کند.
- winreg.HKEY_CURRENT_CONFIG¶
شامل اطلاعاتی دربارهی نمایهی سختافزاری کنونی سیستم رایانهای محلی است.
- winreg.HKEY_DYN_DATA¶
این کلید در نسخههای ویندوز پس از 98 استفاده نمیشود.
حقوق دسترسی¶
برای اطلاعات بیشتر، Registry Key Security and Access را ببینید.
- winreg.KEY_ALL_ACCESS¶
حقوق دسترسی STANDARD_RIGHTS_REQUIRED،
KEY_QUERY_VALUE،KEY_SET_VALUE،KEY_CREATE_SUB_KEY،KEY_ENUMERATE_SUB_KEYS،KEY_NOTIFYوKEY_CREATE_LINKرا ترکیب میکند.
- winreg.KEY_WRITE¶
حقوق دسترسی STANDARD_RIGHTS_WRITE،
KEY_SET_VALUEوKEY_CREATE_SUB_KEYرا ترکیب میکند.
- winreg.KEY_READ¶
مقدارهای STANDARD_RIGHTS_READ،
KEY_QUERY_VALUE،KEY_ENUMERATE_SUB_KEYSوKEY_NOTIFYرا ترکیب میکند.
- winreg.KEY_QUERY_VALUE¶
برای پرسوجوی مقادیر یک کلید رجیستری لازم است.
- winreg.KEY_SET_VALUE¶
برای ایجاد، حذف یا تنظیم یک مقدار رجیستری لازم است.
- winreg.KEY_CREATE_SUB_KEY¶
برای ایجاد یک زیرکلید از یک کلید رجیستری لازم است.
- winreg.KEY_ENUMERATE_SUB_KEYS¶
برای فهرست کردن زیرکلیدهای یک کلید رجیستری مورد نیاز است.
- winreg.KEY_NOTIFY¶
برای درخواست اعلانهای تغییر برای یک کلید رجیستری یا زیرکلیدهای یک کلید رجیستری لازم است.
- winreg.KEY_CREATE_LINK¶
برای استفادهی سیستم رزرو شده است.
مخصوص ۶۴ بیتی¶
برای اطلاعات بیشتر، Accessing an Alternate Registry View را ببینید.
- winreg.KEY_WOW64_64KEY¶
نشان میدهد که یک برنامه در ویندوز ۶۴بیتی باید روی نمای رجیستری ۶۴بیتی (64-bit registry view) عمل کند. در ویندوز ۳۲بیتی، این ثابت نادیده گرفته میشود.
- winreg.KEY_WOW64_32KEY¶
نشان میدهد که یک برنامه در ویندوز ۶۴بیتی باید روی نمای رجیستری ۳۲بیتی (registry view) عمل کند. در ویندوز ۳۲بیتی، این ثابت نادیده گرفته میشود.
انواع مقدار¶
برای اطلاعات بیشتر، Registry Value Types را ببینید.
- winreg.REG_BINARY¶
دادههای دودویی در هر شکلی.
- winreg.REG_DWORD¶
عدد ۳۲ بیتی.
- winreg.REG_DWORD_LITTLE_ENDIAN¶
یک عدد ۳۲بیتی در قالب کوچکاندیان (little-endian). معادل
REG_DWORD.
- winreg.REG_DWORD_BIG_ENDIAN¶
یک عدد ۳۲ بیتی در قالب بزرگاندیان (big-endian).
- winreg.REG_EXPAND_SZ¶
رشتهی پایانیافته با null حاوی ارجاعهایی به متغیرهای محیطی (
%PATH%).
- winreg.REG_LINK¶
یک پیوند نمادین یونیکد.
- winreg.REG_MULTI_SZ¶
دنبالهای از رشتههای پایانیافته با null، که با دو نویسه null پایان مییابد. (پایتون این پایاندهی را بهطور خودکار مدیریت میکند.)
- winreg.REG_NONE¶
فاقد نوع مقدار تعریفشده.
- winreg.REG_QWORD¶
یک عدد ۶۴ بیتی.
اضافه شده در نسخهی 3.6.
- winreg.REG_QWORD_LITTLE_ENDIAN¶
یک عدد ۶۴ بیتی در قالب کوچکاندیان (little-endian). معادل
REG_QWORD.اضافه شده در نسخهی 3.6.
- winreg.REG_RESOURCE_LIST¶
فهرست منابع یک راهانداز دستگاه.
- winreg.REG_FULL_RESOURCE_DESCRIPTOR¶
یک تنظیم سختافزاری.
- winreg.REG_RESOURCE_REQUIREMENTS_LIST¶
فهرستی از منابع سختافزاری.
- winreg.REG_SZ¶
یک رشتهی پایانیافته با null.
اشیای دستهی رجیستری¶
این شیء یک شیء Windows HKEY را پوشش میدهد و هنگامی که شیء نابود میشود، آن را بهطور خودکار میبندد. برای تضمین پاکسازی، میتوانید یا متد Close() را روی شیء فراخوانی کنید، یا تابع CloseKey() را.
تمام توابع رجیستری در این ماژول یکی از این شیءها را برمیگردانند.
تمام توابع رجیستری در این ماژول که یک شیء دسته را میپذیرند، یک عدد صحیح را نیز میپذیرند؛ با این حال، استفاده از شیء دسته توصیه میشود.
اشیای Handle معناشناسی __bool__() را فراهم میکنند -- بنابراین
if handle:
print("Yes")
اگر دسته در حال حاضر معتبر باشد (بسته یا جدا نشده باشد)، Yes را چاپ خواهد کرد.
اشیای دسته را میتوان به یک عدد صحیح تبدیل کرد (برای مثال، با استفاده از تابع توکار int())، که در این صورت مقدار دسته ویندوزی زیرین بازگردانده میشود. همچنین میتوانید از متد Detach() برای بازگرداندن دسته بهصورت عدد صحیح و نیز جدا کردن دسته ویندوزی از شیء دسته استفاده کنید.
- PyHKEY.Close()¶
دستهی ویندوزی زیربنایی را میبندد.
اگر دسته از قبل بسته باشد، خطایی پرتاب نمیشود.
- PyHKEY.Detach()¶
دسته ویندوز را از شیء دسته جدا میکند.
نتیجه، عدد صحیحی است که مقدار دسته را پیش از جدا شدن نگه میدارد. اگر دسته از پیش جدا یا بسته شده باشد، مقدار صفر برگردانده میشود.
پس از فراخوانی این تابع، دسته در عمل نامعتبر میشود، اما دسته بسته نمیشود. شما این تابع را هنگامی فراخوانی میکنید که نیاز دارید دسته Win32 زیربنایی فراتر از طول عمر شیء دسته باقی بماند.
یک رویداد حسابرسی
winreg.PyHKEY.Detachرا با آرگومانkeyپرتاب میکند.
- PyHKEY.__enter__()¶
- PyHKEY.__exit__(*exc_info)¶
شیء HKEY متدهای
__enter__()و__exit__()را پیادهسازی میکند و بنابراین از پروتکل مدیریت زمینه برای دستورwithپشتیبانی میکند:with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: ... # work with key
هنگامی که کنترل از بلوک
withخارج میشود، key را بهطور خودکار میبندد.